From 7e7bdab6f4ee67e04fccf542ea72f3084d28e997 Mon Sep 17 00:00:00 2001 From: Jan Tojnar Date: Thu, 23 Sep 2021 17:13:17 +0200 Subject: Use glib subproject to generate the GIR files Previously, we included C files with documentation comments extracted from GLib libraries in the repository to make it self-contained. Unfortunately, that obscured the source file names, leading to incorrect links in the generated documentation. Since we switched to Meson, we can just use subprojects and the build system will handle it for us. --- .gitlab-ci.yml | 5 + .gitlab-ci/test-msys2-meson.sh | 1 + gir/gio-2.0.c | 43896 -------------------------------------- gir/glib-2.0.c | 42618 ------------------------------------ gir/gmodule-2.0.c | 289 - gir/gobject-2.0.c | 7336 ------- gir/meson.build | 97 +- meson.build | 2 + misc/update-glib-annotations.py | 90 - 9 files changed, 53 insertions(+), 94281 deletions(-) delete mode 100644 gir/gio-2.0.c delete mode 100644 gir/glib-2.0.c delete mode 100644 gir/gmodule-2.0.c delete mode 100644 gir/gobject-2.0.c delete mode 100755 misc/update-glib-annotations.py diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 5f455f50..2c9ff68e 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -16,6 +16,7 @@ example-meson: variables: EXTRA_MESON_FLAGS: "-Ddoctool=enabled -Dgtk_doc=true" script: + - meson subprojects download glib - meson setup ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} _build . - meson compile -C _build - sudo meson install -C _build @@ -35,6 +36,7 @@ example-autotools: variables: EXTRA_MESON_FLAGS: "-Ddoctool=enabled -Dgtk_doc=true" script: + - meson subprojects download glib - meson setup ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} _build . - meson compile -C _build - sudo meson install -C _build @@ -52,6 +54,7 @@ fedora-x86_64-meson: CCACHE_DIR: "${CI_PROJECT_DIR}/_ccache" EXTRA_MESON_FLAGS: "-Ddoctool=enabled -Dgtk_doc=true -Dwerror=true" script: + - meson subprojects download glib - meson setup ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} _build . - meson compile -C _build - meson test -C _build --print-errorlogs --suite=gobject-introspection --no-suite=glib @@ -96,6 +99,7 @@ fedora-x86_64-no-introspection-data: CCACHE_DIR: "${CI_PROJECT_DIR}/_ccache" EXTRA_MESON_FLAGS: "-Dwerror=true" script: + - meson subprojects download glib - meson setup ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} _build . - meson compile -C _build - meson test -C _build --print-errorlogs --suite=gobject-introspection --no-suite=glib @@ -115,6 +119,7 @@ fedora-x86_64-python3.6: CCACHE_DIR: "${CI_PROJECT_DIR}/_ccache" PYENV_VERSION: "3.6.12" script: + - meson subprojects download glib - meson setup ${COMMON_MESON_FLAGS} ${EXTRA_MESON_FLAGS} _build . - meson compile -C _build - meson test -C _build --print-errorlogs --suite=gobject-introspection --no-suite=glib diff --git a/.gitlab-ci/test-msys2-meson.sh b/.gitlab-ci/test-msys2-meson.sh index ead7bf7b..47ded3d1 100644 --- a/.gitlab-ci/test-msys2-meson.sh +++ b/.gitlab-ci/test-msys2-meson.sh @@ -33,6 +33,7 @@ export CCACHE_DIR="${CCACHE_BASEDIR}/_ccache" pip3 install --upgrade --user meson==0.55.3 flake8 mypy==0.790 export PATH="$HOME/.local/bin:$PATH" +meson subprojects download glib export CFLAGS="-Werror" meson -Dcairo=enabled -Ddoctool=enabled --buildtype debug _build cd _build diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c deleted file mode 100644 index 956fed09..00000000 --- a/gir/gio-2.0.c +++ /dev/null @@ -1,43896 +0,0 @@ -/************************************************************/ -/* THIS FILE IS GENERATED DO NOT EDIT */ -/************************************************************/ - -/** - * GAction: - * - * #GAction is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GAction: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.28 - */ - - -/** - * GAction:name: - * - * The name of the action. This is mostly meaningful for identifying - * the action once it has been added to a #GActionGroup. It is immutable. - * - * Since: 2.28 - */ - - -/** - * GAction:parameter-type: - * - * The type of the parameter that must be given when activating the - * action. This is immutable, and may be %NULL if no parameter is needed when - * activating the action. - * - * Since: 2.28 - */ - - -/** - * GAction:state: - * - * The state of the action, or %NULL if the action is stateless. - * - * Since: 2.28 - */ - - -/** - * GAction:state-type: - * - * The #GVariantType of the state that the action has, or %NULL if the - * action is stateless. This is immutable. - * - * Since: 2.28 - */ - - -/** - * GActionEntry: - * @name: the name of the action - * @activate: the callback to connect to the "activate" signal of the - * action. Since GLib 2.40, this can be %NULL for stateful - * actions, in which case the default handler is used. For - * boolean-stated actions with no parameter, this is a - * toggle. For other state types (and parameter type equal - * to the state type) this will be a function that - * just calls @change_state (which you should provide). - * @parameter_type: the type of the parameter that must be passed to the - * activate function for this action, given as a single - * GVariant type string (or %NULL for no parameter) - * @state: the initial state for this action, given in - * [GVariant text format][gvariant-text]. The state is parsed - * with no extra type information, so type tags must be added to - * the string if they are necessary. Stateless actions should - * give %NULL here. - * @change_state: the callback to connect to the "change-state" signal - * of the action. All stateful actions should provide a - * handler here; stateless actions should not. - * - * This struct defines a single action. It is for use with - * g_action_map_add_action_entries(). - * - * The order of the items in the structure are intended to reflect - * frequency of use. It is permissible to use an incomplete initialiser - * in order to leave some of the later values as %NULL. All values - * after @name are optional. Additional optional fields may be added in - * the future. - * - * See g_action_map_add_action_entries() for an example. - */ - - -/** - * GActionGroup: - * - * #GActionGroup is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GActionGroup::action-added: - * @action_group: the #GActionGroup that changed - * @action_name: the name of the action in @action_group - * - * Signals that a new action was just added to the group. - * This signal is emitted after the action has been added - * and is now visible. - * - * Since: 2.28 - */ - - -/** - * GActionGroup::action-enabled-changed: - * @action_group: the #GActionGroup that changed - * @action_name: the name of the action in @action_group - * @enabled: whether the action is enabled or not - * - * Signals that the enabled status of the named action has changed. - * - * Since: 2.28 - */ - - -/** - * GActionGroup::action-removed: - * @action_group: the #GActionGroup that changed - * @action_name: the name of the action in @action_group - * - * Signals that an action is just about to be removed from the group. - * This signal is emitted before the action is removed, so the action - * is still visible and can be queried from the signal handler. - * - * Since: 2.28 - */ - - -/** - * GActionGroup::action-state-changed: - * @action_group: the #GActionGroup that changed - * @action_name: the name of the action in @action_group - * @value: the new value of the state - * - * Signals that the state of the named action has changed. - * - * Since: 2.28 - */ - - -/** - * GActionGroupInterface: - * @has_action: the virtual function pointer for g_action_group_has_action() - * @list_actions: the virtual function pointer for g_action_group_list_actions() - * @get_action_parameter_type: the virtual function pointer for g_action_group_get_action_parameter_type() - * @get_action_state_type: the virtual function pointer for g_action_group_get_action_state_type() - * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint() - * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled() - * @get_action_state: the virtual function pointer for g_action_group_get_action_state() - * @change_action_state: the virtual function pointer for g_action_group_change_action_state() - * @query_action: the virtual function pointer for g_action_group_query_action() - * @activate_action: the virtual function pointer for g_action_group_activate_action() - * @action_added: the class closure for the #GActionGroup::action-added signal - * @action_removed: the class closure for the #GActionGroup::action-removed signal - * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal - * @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal - * - * The virtual function table for #GActionGroup. - * - * Since: 2.28 - */ - - -/** - * GActionInterface: - * @get_name: the virtual function pointer for g_action_get_name() - * @get_parameter_type: the virtual function pointer for g_action_get_parameter_type() - * @get_state_type: the virtual function pointer for g_action_get_state_type() - * @get_state_hint: the virtual function pointer for g_action_get_state_hint() - * @get_enabled: the virtual function pointer for g_action_get_enabled() - * @get_state: the virtual function pointer for g_action_get_state() - * @change_state: the virtual function pointer for g_action_change_state() - * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an - * 'activate' signal but that implementations of it may have one. - * - * The virtual function table for #GAction. - * - * Since: 2.28 - */ - - -/** - * GActionMap: - * - * #GActionMap is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GActionMapInterface: - * @lookup_action: the virtual function pointer for g_action_map_lookup_action() - * @add_action: the virtual function pointer for g_action_map_add_action() - * @remove_action: the virtual function pointer for g_action_map_remove_action() - * - * The virtual function table for #GActionMap. - * - * Since: 2.32 - */ - - -/** - * GAppInfoMonitor: - * - * The only thing you can do with this is to get it via - * g_app_info_monitor_get() and connect to the "changed" signal. - * - * Since: 2.40 - */ - - -/** - * GAppInfoMonitor::changed: - * - * Signal emitted when the app info database for changes (ie: newly installed - * or removed applications). - */ - - -/** - * GAppLaunchContext::launch-failed: - * @context: the object emitting the signal - * @startup_notify_id: the startup notification id for the failed launch - * - * The ::launch-failed signal is emitted when a #GAppInfo launch - * fails. The startup notification id is provided, so that the launcher - * can cancel the startup notification. - * - * Since: 2.36 - */ - - -/** - * GAppLaunchContext::launched: - * @context: the object emitting the signal - * @info: the #GAppInfo that was just launched - * @platform_data: additional platform-specific data for this launch - * - * The ::launched signal is emitted when a #GAppInfo is successfully - * launched. The @platform_data is an GVariant dictionary mapping - * strings to variants (ie a{sv}), which contains additional, - * platform-specific data about this launch. On UNIX, at least the - * "pid" and "startup-notification-id" keys will be present. - * - * Since: 2.36 - */ - - -/** - * GApplication: - * - * #GApplication is an opaque data structure and can only be accessed - * using the following functions. - * - * Since: 2.28 - */ - - -/** - * GApplication::activate: - * @application: the application - * - * The ::activate signal is emitted on the primary instance when an - * activation occurs. See g_application_activate(). - */ - - -/** - * GApplication::command-line: - * @application: the application - * @command_line: a #GApplicationCommandLine representing the - * passed commandline - * - * The ::command-line signal is emitted on the primary instance when - * a commandline is not handled locally. See g_application_run() and - * the #GApplicationCommandLine documentation for more information. - * - * Returns: An integer that is set as the exit status for the calling - * process. See g_application_command_line_set_exit_status(). - */ - - -/** - * GApplication::handle-local-options: - * @application: the application - * @options: the options dictionary - * - * The ::handle-local-options signal is emitted on the local instance - * after the parsing of the commandline options has occurred. - * - * You can add options to be recognised during commandline option - * parsing using g_application_add_main_option_entries() and - * g_application_add_option_group(). - * - * Signal handlers can inspect @options (along with values pointed to - * from the @arg_data of an installed #GOptionEntrys) in order to - * decide to perform certain actions, including direct local handling - * (which may be useful for options like --version). - * - * In the event that the application is marked - * %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will - * send the @options dictionary to the primary instance where it can be - * read with g_application_command_line_get_options_dict(). The signal - * handler can modify the dictionary before returning, and the - * modified dictionary will be sent. - * - * In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set, - * "normal processing" will treat the remaining uncollected command - * line arguments as filenames or URIs. If there are no arguments, - * the application is activated by g_application_activate(). One or - * more arguments results in a call to g_application_open(). - * - * If you want to handle the local commandline arguments for yourself - * by converting them to calls to g_application_open() or - * g_action_group_activate_action() then you must be sure to register - * the application first. You should probably not call - * g_application_activate() for yourself, however: just return -1 and - * allow the default handler to do it for you. This will ensure that - * the `--gapplication-service` switch works properly (i.e. no activation - * in that case). - * - * Note that this signal is emitted from the default implementation of - * local_command_line(). If you override that function and don't - * chain up then this signal will never be emitted. - * - * You can override local_command_line() if you need more powerful - * capabilities than what is provided here, but this should not - * normally be required. - * - * Returns: an exit code. If you have handled your options and want - * to exit the process, return a non-negative option, 0 for success, - * and a positive value for failure. To continue, return -1 to let - * the default option processing continue. - * Since: 2.40 - */ - - -/** - * GApplication::name-lost: - * @application: the application - * - * The ::name-lost signal is emitted only on the registered primary instance - * when a new instance has taken over. This can only happen if the application - * is using the %G_APPLICATION_ALLOW_REPLACEMENT flag. - * - * The default handler for this signal calls g_application_quit(). - * - * Returns: %TRUE if the signal has been handled - * Since: 2.60 - */ - - -/** - * GApplication::open: - * @application: the application - * @files: (array length=n_files) (element-type GFile): an array of #GFiles - * @n_files: the length of @files - * @hint: a hint provided by the calling instance - * - * The ::open signal is emitted on the primary instance when there are - * files to open. See g_application_open() for more information. - */ - - -/** - * GApplication::shutdown: - * @application: the application - * - * The ::shutdown signal is emitted only on the registered primary instance - * immediately after the main loop terminates. - */ - - -/** - * GApplication::startup: - * @application: the application - * - * The ::startup signal is emitted on the primary instance immediately - * after registration. See g_application_register(). - */ - - -/** - * GApplication:is-busy: - * - * Whether the application is currently marked as busy through - * g_application_mark_busy() or g_application_bind_busy_property(). - * - * Since: 2.44 - */ - - -/** - * GApplicationClass: - * @startup: invoked on the primary instance immediately after registration - * @shutdown: invoked only on the registered primary instance immediately - * after the main loop terminates - * @activate: invoked on the primary instance when an activation occurs - * @open: invoked on the primary instance when there are files to open - * @command_line: invoked on the primary instance when a command-line is - * not handled locally - * @local_command_line: invoked (locally). The virtual function has the chance - * to inspect (and possibly replace) command line arguments. See - * g_application_run() for more information. Also see the - * #GApplication::handle-local-options signal, which is a simpler - * alternative to handling some commandline options locally - * @before_emit: invoked on the primary instance before 'activate', 'open', - * 'command-line' or any action invocation, gets the 'platform data' from - * the calling instance - * @after_emit: invoked on the primary instance after 'activate', 'open', - * 'command-line' or any action invocation, gets the 'platform data' from - * the calling instance - * @add_platform_data: invoked (locally) to add 'platform data' to be sent to - * the primary instance when activating, opening or invoking actions - * @quit_mainloop: Used to be invoked on the primary instance when the use - * count of the application drops to zero (and after any inactivity - * timeout, if requested). Not used anymore since 2.32 - * @run_mainloop: Used to be invoked on the primary instance from - * g_application_run() if the use-count is non-zero. Since 2.32, - * GApplication is iterating the main context directly and is not - * using @run_mainloop anymore - * @dbus_register: invoked locally during registration, if the application is - * using its D-Bus backend. You can use this to export extra objects on the - * bus, that need to exist before the application tries to own the bus name. - * The function is passed the #GDBusConnection to to session bus, and the - * object path that #GApplication will use to export is D-Bus API. - * If this function returns %TRUE, registration will proceed; otherwise - * registration will abort. Since: 2.34 - * @dbus_unregister: invoked locally during unregistration, if the application - * is using its D-Bus backend. Use this to undo anything done by - * the @dbus_register vfunc. Since: 2.34 - * @handle_local_options: invoked locally after the parsing of the commandline - * options has occurred. Since: 2.40 - * @name_lost: invoked when another instance is taking over the name. Since: 2.60 - * - * Virtual function table for #GApplication. - * - * Since: 2.28 - */ - - -/** - * GApplicationCommandLine: - * - * #GApplicationCommandLine is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GApplicationCommandLineClass: - * - * The #GApplicationCommandLineClass-struct - * contains private data only. - * - * Since: 2.28 - */ - - -/** - * GBytesIcon:bytes: - * - * The bytes containing the icon. - */ - - -/** - * GCancellable::cancelled: - * @cancellable: a #GCancellable. - * - * Emitted when the operation has been cancelled. - * - * Can be used by implementations of cancellable operations. If the - * operation is cancelled from another thread, the signal will be - * emitted in the thread that cancelled the operation, not the - * thread that is running the operation. - * - * Note that disconnecting from this signal (or any signal) in a - * multi-threaded program is prone to race conditions. For instance - * it is possible that a signal handler may be invoked even after - * a call to g_signal_handler_disconnect() for that handler has - * already returned. - * - * There is also a problem when cancellation happens right before - * connecting to the signal. If this happens the signal will - * unexpectedly not be emitted, and checking before connecting to - * the signal leaves a race condition where this is still happening. - * - * In order to make it safe and easy to connect handlers there - * are two helper functions: g_cancellable_connect() and - * g_cancellable_disconnect() which protect against problems - * like this. - * - * An example of how to us this: - * |[ - * // Make sure we don't do unnecessary work if already cancelled - * if (g_cancellable_set_error_if_cancelled (cancellable, error)) - * return; - * - * // Set up all the data needed to be able to handle cancellation - * // of the operation - * my_data = my_data_new (...); - * - * id = 0; - * if (cancellable) - * id = g_cancellable_connect (cancellable, - * G_CALLBACK (cancelled_handler) - * data, NULL); - * - * // cancellable operation here... - * - * g_cancellable_disconnect (cancellable, id); - * - * // cancelled_handler is never called after this, it is now safe - * // to free the data - * my_data_free (my_data); - * ]| - * - * Note that the cancelled signal is emitted in the thread that - * the user cancelled from, which may be the main thread. So, the - * cancellable signal should not do something that can block. - */ - - -/** - * GCharsetConverter: - * - * Conversions between character sets. - */ - - -/** - * GCredentials: - * - * The #GCredentials structure contains only private data and - * should only be accessed using the provided API. - * - * Since: 2.26 - */ - - -/** - * GCredentialsClass: - * - * Class structure for #GCredentials. - * - * Since: 2.26 - */ - - -/** - * GDBusActionGroup: - * - * #GDBusActionGroup is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GDBusAuthMechanism:credentials: - * - * If authenticating as a server, this property contains the - * received credentials, if any. - * - * If authenticating as a client, the property contains the - * credentials that were sent, if any. - */ - - -/** - * GDBusAuthObserver: - * - * The #GDBusAuthObserver structure contains only private data and - * should only be accessed using the provided API. - * - * Since: 2.26 - */ - - -/** - * GDBusAuthObserver::allow-mechanism: - * @observer: The #GDBusAuthObserver emitting the signal. - * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. - * - * Emitted to check if @mechanism is allowed to be used. - * - * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. - * Since: 2.34 - */ - - -/** - * GDBusAuthObserver::authorize-authenticated-peer: - * @observer: The #GDBusAuthObserver emitting the signal. - * @stream: A #GIOStream for the #GDBusConnection. - * @credentials: (nullable): Credentials received from the peer or %NULL. - * - * Emitted to check if a peer that is successfully authenticated - * is authorized. - * - * Returns: %TRUE if the peer is authorized, %FALSE if not. - * Since: 2.26 - */ - - -/** - * GDBusAuthObserverClass: - * @authorize_authenticated_peer: Signal class handler for the #GDBusAuthObserver::authorize-authenticated-peer signal. - * - * Class structure for #GDBusAuthObserverClass. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection: - * - * The #GDBusConnection structure contains only private data and - * should only be accessed using the provided API. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection::closed: - * @connection: the #GDBusConnection emitting the signal - * @remote_peer_vanished: %TRUE if @connection is closed because the - * remote peer closed its end of the connection - * @error: (nullable): a #GError with more details about the event or %NULL - * - * Emitted when the connection is closed. - * - * The cause of this event can be - * - * - If g_dbus_connection_close() is called. In this case - * @remote_peer_vanished is set to %FALSE and @error is %NULL. - * - * - If the remote peer closes the connection. In this case - * @remote_peer_vanished is set to %TRUE and @error is set. - * - * - If the remote peer sends invalid or malformed data. In this - * case @remote_peer_vanished is set to %FALSE and @error is set. - * - * Upon receiving this signal, you should give up your reference to - * @connection. You are guaranteed that this signal is emitted only - * once. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection:address: - * - * A D-Bus address specifying potential endpoints that can be used - * when establishing the connection. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection:authentication-observer: - * - * A #GDBusAuthObserver object to assist in the authentication process or %NULL. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection:capabilities: - * - * Flags from the #GDBusCapabilityFlags enumeration - * representing connection features negotiated with the other peer. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection:closed: - * - * A boolean specifying whether the connection has been closed. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection:exit-on-close: - * - * A boolean specifying whether the process will be terminated (by - * calling `raise(SIGTERM)`) if the connection is closed by the - * remote peer. - * - * Note that #GDBusConnection objects returned by g_bus_get_finish() - * and g_bus_get_sync() will (usually) have this property set to %TRUE. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection:flags: - * - * Flags from the #GDBusConnectionFlags enumeration. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection:guid: - * - * The GUID of the peer performing the role of server when - * authenticating. - * - * If you are constructing a #GDBusConnection and pass - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the - * #GDBusConnection:flags property then you **must** also set this - * property to a valid guid. - * - * If you are constructing a #GDBusConnection and pass - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the - * #GDBusConnection:flags property you will be able to read the GUID - * of the other peer here after the connection has been successfully - * initialized. - * - * Note that the - * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) - * uses the term ‘UUID’ to refer to this, whereas GLib consistently uses the - * term ‘GUID’ for historical reasons. - * - * Despite its name, the format of #GDBusConnection:guid does not follow - * [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122) or the Microsoft - * GUID format. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection:locked: - * - * A boolean specifying whether the message is locked. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection:stream: - * - * The underlying #GIOStream used for I/O. - * - * If this is passed on construction and is a #GSocketConnection, - * then the corresponding #GSocket will be put into non-blocking mode. - * - * While the #GDBusConnection is active, it will interact with this - * stream from a worker thread, so it is not safe to interact with - * the stream directly. - * - * Since: 2.26 - */ - - -/** - * GDBusConnection:unique-name: - * - * The unique name as assigned by the message bus or %NULL if the - * connection is not open or not a message bus connection. - * - * Since: 2.26 - */ - - -/** - * GDBusConnectionClass: - * @closed: Signal class handler for the #GDBusConnection::closed signal. - * - * Class structure for #GDBusConnection. - * - * Since: 2.26 - */ - - -/** - * GDBusInterfaceSkeleton::g-authorize-method: - * @interface: The #GDBusInterfaceSkeleton emitting the signal. - * @invocation: A #GDBusMethodInvocation. - * - * Emitted when a method is invoked by a remote caller and used to - * determine if the method call is authorized. - * - * Note that this signal is emitted in a thread dedicated to - * handling the method call so handlers are allowed to perform - * blocking IO. This means that it is appropriate to call e.g. - * [polkit_authority_check_authorization_sync()](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync) - * with the - * [POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS) - * flag set. - * - * If %FALSE is returned then no further handlers are run and the - * signal handler must take a reference to @invocation and finish - * handling the call (e.g. return an error via - * g_dbus_method_invocation_return_error()). - * - * Otherwise, if %TRUE is returned, signal emission continues. If no - * handlers return %FALSE, then the method is dispatched. If - * @interface has an enclosing #GDBusObjectSkeleton, then the - * #GDBusObjectSkeleton::authorize-method signal handlers run before - * the handlers for this signal. - * - * The default class handler just returns %TRUE. - * - * Please note that the common case is optimized: if no signals - * handlers are connected and the default class handler isn't - * overridden (for both @interface and the enclosing - * #GDBusObjectSkeleton, if any) and #GDBusInterfaceSkeleton:g-flags does - * not have the - * %G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD - * flags set, no dedicated thread is ever used and the call will be - * handled in the same thread as the object that @interface belongs - * to was exported in. - * - * Returns: %TRUE if the call is authorized, %FALSE otherwise. - * Since: 2.30 - */ - - -/** - * GDBusInterfaceSkeleton:g-flags: - * - * Flags from the #GDBusInterfaceSkeletonFlags enumeration. - * - * Since: 2.30 - */ - - -/** - * GDBusMenuModel: - * - * #GDBusMenuModel is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GDBusMessage: - * - * The #GDBusMessage structure contains only private data and should - * only be accessed using the provided API. - * - * Since: 2.26 - */ - - -/** - * GDBusMessageClass: - * - * Class structure for #GDBusMessage. - * - * Since: 2.26 - */ - - -/** - * GDBusMethodInvocation: - * - * The #GDBusMethodInvocation structure contains only private data and - * should only be accessed using the provided API. - * - * Since: 2.26 - */ - - -/** - * GDBusMethodInvocationClass: - * - * Class structure for #GDBusMethodInvocation. - * - * Since: 2.26 - */ - - -/** - * GDBusObject: - * - * #GDBusObject is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GDBusObject::interface-added: - * @object: The #GDBusObject emitting the signal. - * @interface: The #GDBusInterface that was added. - * - * Emitted when @interface is added to @object. - * - * Since: 2.30 - */ - - -/** - * GDBusObject::interface-removed: - * @object: The #GDBusObject emitting the signal. - * @interface: The #GDBusInterface that was removed. - * - * Emitted when @interface is removed from @object. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManager: - * - * #GDBusObjectManager is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GDBusObjectManager::interface-added: - * @manager: The #GDBusObjectManager emitting the signal. - * @object: The #GDBusObject on which an interface was added. - * @interface: The #GDBusInterface that was added. - * - * Emitted when @interface is added to @object. - * - * This signal exists purely as a convenience to avoid having to - * connect signals to all objects managed by @manager. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManager::interface-removed: - * @manager: The #GDBusObjectManager emitting the signal. - * @object: The #GDBusObject on which an interface was removed. - * @interface: The #GDBusInterface that was removed. - * - * Emitted when @interface has been removed from @object. - * - * This signal exists purely as a convenience to avoid having to - * connect signals to all objects managed by @manager. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManager::object-added: - * @manager: The #GDBusObjectManager emitting the signal. - * @object: The #GDBusObject that was added. - * - * Emitted when @object is added to @manager. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManager::object-removed: - * @manager: The #GDBusObjectManager emitting the signal. - * @object: The #GDBusObject that was removed. - * - * Emitted when @object is removed from @manager. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerClient::interface-proxy-properties-changed: - * @manager: The #GDBusObjectManagerClient emitting the signal. - * @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing. - * @interface_proxy: The #GDBusProxy that has properties that are changing. - * @changed_properties: A #GVariant containing the properties that changed (type: `a{sv}`). - * @invalidated_properties: (array zero-terminated=1) (element-type utf8): A %NULL terminated - * array of properties that were invalidated. - * - * Emitted when one or more D-Bus properties on proxy changes. The - * local cache has already been updated when this signal fires. Note - * that both @changed_properties and @invalidated_properties are - * guaranteed to never be %NULL (either may be empty though). - * - * This signal exists purely as a convenience to avoid having to - * connect signals to all interface proxies managed by @manager. - * - * This signal is emitted in the - * [thread-default main context][g-main-context-push-thread-default] - * that @manager was constructed in. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerClient::interface-proxy-signal: - * @manager: The #GDBusObjectManagerClient emitting the signal. - * @object_proxy: The #GDBusObjectProxy on which an interface is emitting a D-Bus signal. - * @interface_proxy: The #GDBusProxy that is emitting a D-Bus signal. - * @sender_name: The sender of the signal or NULL if the connection is not a bus connection. - * @signal_name: The signal name. - * @parameters: A #GVariant tuple with parameters for the signal. - * - * Emitted when a D-Bus signal is received on @interface_proxy. - * - * This signal exists purely as a convenience to avoid having to - * connect signals to all interface proxies managed by @manager. - * - * This signal is emitted in the - * [thread-default main context][g-main-context-push-thread-default] - * that @manager was constructed in. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerClient:bus-type: - * - * If this property is not %G_BUS_TYPE_NONE, then - * #GDBusObjectManagerClient:connection must be %NULL and will be set to the - * #GDBusConnection obtained by calling g_bus_get() with the value - * of this property. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerClient:connection: - * - * The #GDBusConnection to use. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerClient:flags: - * - * Flags from the #GDBusObjectManagerClientFlags enumeration. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerClient:get-proxy-type-destroy-notify: - * - * A #GDestroyNotify for the #gpointer user_data in #GDBusObjectManagerClient:get-proxy-type-user-data. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerClient:get-proxy-type-func: - * - * The #GDBusProxyTypeFunc to use when determining what #GType to - * use for interface proxies or %NULL. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerClient:get-proxy-type-user-data: - * - * The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerClient:name: - * - * The well-known name or unique name that the manager is for. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerClient:name-owner: - * - * The unique name that owns #GDBusObjectManagerClient:name or %NULL if - * no-one is currently owning the name. Connect to the - * #GObject::notify signal to track changes to this property. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerClient:object-path: - * - * The object path the manager is for. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerServer:connection: - * - * The #GDBusConnection to export objects on. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectManagerServer:object-path: - * - * The object path to register the manager object at. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectProxy:g-connection: - * - * The connection of the proxy. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectProxy:g-object-path: - * - * The object path of the proxy. - * - * Since: 2.30 - */ - - -/** - * GDBusObjectSkeleton::authorize-method: - * @object: The #GDBusObjectSkeleton emitting the signal. - * @interface: The #GDBusInterfaceSkeleton that @invocation is for. - * @invocation: A #GDBusMethodInvocation. - * - * Emitted when a method is invoked by a remote caller and used to - * determine if the method call is authorized. - * - * This signal is like #GDBusInterfaceSkeleton's - * #GDBusInterfaceSkeleton::g-authorize-method signal, - * except that it is for the enclosing object. - * - * The default class handler just returns %TRUE. - * - * Returns: %TRUE if the call is authorized, %FALSE otherwise. - * Since: 2.30 - */ - - -/** - * GDBusObjectSkeleton:g-object-path: - * - * The object path where the object is exported. - * - * Since: 2.30 - */ - - -/** - * GDBusProxy::g-properties-changed: - * @proxy: The #GDBusProxy emitting the signal. - * @changed_properties: A #GVariant containing the properties that changed (type: `a{sv}`) - * @invalidated_properties: A %NULL terminated array of properties that was invalidated - * - * Emitted when one or more D-Bus properties on @proxy changes. The - * local cache has already been updated when this signal fires. Note - * that both @changed_properties and @invalidated_properties are - * guaranteed to never be %NULL (either may be empty though). - * - * If the proxy has the flag - * %G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then - * @invalidated_properties will always be empty. - * - * This signal corresponds to the - * `PropertiesChanged` D-Bus signal on the - * `org.freedesktop.DBus.Properties` interface. - * - * Since: 2.26 - */ - - -/** - * GDBusProxy::g-signal: - * @proxy: The #GDBusProxy emitting the signal. - * @sender_name: (nullable): The sender of the signal or %NULL if the connection is not a bus connection. - * @signal_name: The name of the signal. - * @parameters: A #GVariant tuple with parameters for the signal. - * - * Emitted when a signal from the remote object and interface that @proxy is for, has been received. - * - * Since: 2.26 - */ - - -/** - * GDBusProxy:g-bus-type: - * - * If this property is not %G_BUS_TYPE_NONE, then - * #GDBusProxy:g-connection must be %NULL and will be set to the - * #GDBusConnection obtained by calling g_bus_get() with the value - * of this property. - * - * Since: 2.26 - */ - - -/** - * GDBusProxy:g-connection: - * - * The #GDBusConnection the proxy is for. - * - * Since: 2.26 - */ - - -/** - * GDBusProxy:g-default-timeout: - * - * The timeout to use if -1 (specifying default timeout) is passed - * as @timeout_msec in the g_dbus_proxy_call() and - * g_dbus_proxy_call_sync() functions. - * - * This allows applications to set a proxy-wide timeout for all - * remote method invocations on the proxy. If this property is -1, - * the default timeout (typically 25 seconds) is used. If set to - * %G_MAXINT, then no timeout is used. - * - * Since: 2.26 - */ - - -/** - * GDBusProxy:g-flags: - * - * Flags from the #GDBusProxyFlags enumeration. - * - * Since: 2.26 - */ - - -/** - * GDBusProxy:g-interface-info: - * - * Ensure that interactions with this proxy conform to the given - * interface. This is mainly to ensure that malformed data received - * from the other peer is ignored. The given #GDBusInterfaceInfo is - * said to be the "expected interface". - * - * The checks performed are: - * - When completing a method call, if the type signature of - * the reply message isn't what's expected, the reply is - * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT. - * - * - Received signals that have a type signature mismatch are dropped and - * a warning is logged via g_warning(). - * - * - Properties received via the initial `GetAll()` call or via the - * `::PropertiesChanged` signal (on the - * [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) - * interface) or set using g_dbus_proxy_set_cached_property() - * with a type signature mismatch are ignored and a warning is - * logged via g_warning(). - * - * Note that these checks are never done on methods, signals and - * properties that are not referenced in the given - * #GDBusInterfaceInfo, since extending a D-Bus interface on the - * service-side is not considered an ABI break. - * - * Since: 2.26 - */ - - -/** - * GDBusProxy:g-interface-name: - * - * The D-Bus interface name the proxy is for. - * - * Since: 2.26 - */ - - -/** - * GDBusProxy:g-name: - * - * The well-known or unique name that the proxy is for. - * - * Since: 2.26 - */ - - -/** - * GDBusProxy:g-name-owner: - * - * The unique name that owns #GDBusProxy:g-name or %NULL if no-one - * currently owns that name. You may connect to #GObject::notify signal to - * track changes to this property. - * - * Since: 2.26 - */ - - -/** - * GDBusProxy:g-object-path: - * - * The object path the proxy is for. - * - * Since: 2.26 - */ - - -/** - * GDBusServer: - * - * The #GDBusServer structure contains only private data and - * should only be accessed using the provided API. - * - * Since: 2.26 - */ - - -/** - * GDBusServer::new-connection: - * @server: The #GDBusServer emitting the signal. - * @connection: A #GDBusConnection for the new connection. - * - * Emitted when a new authenticated connection has been made. Use - * g_dbus_connection_get_peer_credentials() to figure out what - * identity (if any), was authenticated. - * - * If you want to accept the connection, take a reference to the - * @connection object and return %TRUE. When you are done with the - * connection call g_dbus_connection_close() and give up your - * reference. Note that the other peer may disconnect at any time - - * a typical thing to do when accepting a connection is to listen to - * the #GDBusConnection::closed signal. - * - * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD - * then the signal is emitted in a new thread dedicated to the - * connection. Otherwise the signal is emitted in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread that @server was constructed in. - * - * You are guaranteed that signal handlers for this signal runs - * before incoming messages on @connection are processed. This means - * that it's suitable to call g_dbus_connection_register_object() or - * similar from the signal handler. - * - * Returns: %TRUE to claim @connection, %FALSE to let other handlers - * run. - * Since: 2.26 - */ - - -/** - * GDBusServer:active: - * - * Whether the server is currently active. - * - * Since: 2.26 - */ - - -/** - * GDBusServer:address: - * - * The D-Bus address to listen on. - * - * Since: 2.26 - */ - - -/** - * GDBusServer:authentication-observer: - * - * A #GDBusAuthObserver object to assist in the authentication process or %NULL. - * - * Since: 2.26 - */ - - -/** - * GDBusServer:client-address: - * - * The D-Bus address that clients can use. - * - * Since: 2.26 - */ - - -/** - * GDBusServer:flags: - * - * Flags from the #GDBusServerFlags enumeration. - * - * Since: 2.26 - */ - - -/** - * GDBusServer:guid: - * - * The GUID of the server. - * - * See #GDBusConnection:guid for more details. - * - * Since: 2.26 - */ - - -/** - * GDBusServerClass: - * @new_connection: Signal class handler for the #GDBusServer::new-connection signal. - * - * Class structure for #GDBusServer. - * - * Since: 2.26 - */ - - -/** - * GDataInputStream:byte-order: - * - * The :byte-order property determines the byte ordering that - * is used when reading multi-byte entities (such as integers) - * from the stream. - */ - - -/** - * GDataInputStream:newline-type: - * - * The :newline-type property determines what is considered - * as a line ending when reading complete lines from the stream. - */ - - -/** - * GDataOutputStream:byte-order: - * - * Determines the byte ordering that is used when writing - * multi-byte entities (such as integers) to the stream. - */ - - -/** - * GDesktopAppInfo: - * - * Information about an installed application from a desktop file. - */ - - -/** - * GDesktopAppInfo:filename: - * - * The origin filename of this #GDesktopAppInfo - */ - - -/** - * GDesktopAppInfoLookup: - * - * #GDesktopAppInfoLookup is an opaque data structure and can only be accessed - * using the following functions. - * - * Deprecated: 2.28: The #GDesktopAppInfoLookup interface is deprecated and - * unused by GIO. - */ - - -/** - * GDrive::changed: - * @drive: a #GDrive. - * - * Emitted when the drive's state has changed. - */ - - -/** - * GDrive::disconnected: - * @drive: a #GDrive. - * - * This signal is emitted when the #GDrive have been - * disconnected. If the recipient is holding references to the - * object they should release them so the object can be - * finalized. - */ - - -/** - * GDrive::eject-button: - * @drive: a #GDrive. - * - * Emitted when the physical eject button (if any) of a drive has - * been pressed. - */ - - -/** - * GDrive::stop-button: - * @drive: a #GDrive. - * - * Emitted when the physical stop button (if any) of a drive has - * been pressed. - * - * Since: 2.22 - */ - - -/** - * GDtlsClientConnection: - * - * Abstract base class for the backend-specific client connection - * type. - * - * Since: 2.48 - */ - - -/** - * GDtlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray) - * - * A list of the distinguished names of the Certificate Authorities - * that the server will accept client certificates signed by. If the - * server requests a client certificate during the handshake, then - * this property will be set after the handshake completes. - * - * Each item in the list is a #GByteArray which contains the complete - * subject DN of the certificate authority. - * - * Since: 2.48 - */ - - -/** - * GDtlsClientConnection:server-identity: - * - * A #GSocketConnectable describing the identity of the server that - * is expected on the other end of the connection. - * - * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in - * #GDtlsClientConnection:validation-flags, this object will be used - * to determine the expected identify of the remote end of the - * connection; if #GDtlsClientConnection:server-identity is not set, - * or does not match the identity presented by the server, then the - * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail. - * - * In addition to its use in verifying the server certificate, - * this is also used to give a hint to the server about what - * certificate we expect, which is useful for servers that serve - * virtual hosts. - * - * Since: 2.48 - */ - - -/** - * GDtlsClientConnection:validation-flags: - * - * What steps to perform when validating a certificate received from - * a server. Server certificates that fail to validate in any of the - * ways indicated here will be rejected unless the application - * overrides the default via #GDtlsConnection::accept-certificate. - * - * Since: 2.48 - */ - - -/** - * GDtlsConnection: - * - * Abstract base class for the backend-specific #GDtlsClientConnection - * and #GDtlsServerConnection types. - * - * Since: 2.48 - */ - - -/** - * GDtlsConnection::accept-certificate: - * @conn: a #GDtlsConnection - * @peer_cert: the peer's #GTlsCertificate - * @errors: the problems with @peer_cert. - * - * Emitted during the TLS handshake after the peer certificate has - * been received. You can examine @peer_cert's certification path by - * calling g_tls_certificate_get_issuer() on it. - * - * For a client-side connection, @peer_cert is the server's - * certificate, and the signal will only be emitted if the - * certificate was not acceptable according to @conn's - * #GDtlsClientConnection:validation_flags. If you would like the - * certificate to be accepted despite @errors, return %TRUE from the - * signal handler. Otherwise, if no handler accepts the certificate, - * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE. - * - * For a server-side connection, @peer_cert is the certificate - * presented by the client, if this was requested via the server's - * #GDtlsServerConnection:authentication_mode. On the server side, - * the signal is always emitted when the client presents a - * certificate, and the certificate will only be accepted if a - * handler returns %TRUE. - * - * Note that if this signal is emitted as part of asynchronous I/O - * in the main thread, then you should not attempt to interact with - * the user before returning from the signal handler. If you want to - * let the user decide whether or not to accept the certificate, you - * would have to return %FALSE from the signal handler on the first - * attempt, and then after the connection attempt returns a - * %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and - * if the user decides to accept the certificate, remember that fact, - * create a new connection, and return %TRUE from the signal handler - * the next time. - * - * If you are doing I/O in another thread, you do not - * need to worry about this, and can simply block in the signal - * handler until the UI thread returns an answer. - * - * Returns: %TRUE to accept @peer_cert (which will also - * immediately end the signal emission). %FALSE to allow the signal - * emission to continue, which will cause the handshake to fail if - * no one else overrides it. - * Since: 2.48 - */ - - -/** - * GDtlsConnection:advertised-protocols: (nullable) - * - * The list of application-layer protocols that the connection - * advertises that it is willing to speak. See - * g_dtls_connection_set_advertised_protocols(). - * - * Since: 2.60 - */ - - -/** - * GDtlsConnection:base-socket: - * - * The #GDatagramBased that the connection wraps. Note that this may be any - * implementation of #GDatagramBased, not just a #GSocket. - * - * Since: 2.48 - */ - - -/** - * GDtlsConnection:certificate: - * - * The connection's certificate; see - * g_dtls_connection_set_certificate(). - * - * Since: 2.48 - */ - - -/** - * GDtlsConnection:ciphersuite-name: (nullable) - * - * The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name(). - * - * Since: 2.70 - */ - - -/** - * GDtlsConnection:database: (nullable) - * - * The certificate database to use when verifying this TLS connection. - * If no certificate database is set, then the default database will be - * used. See g_tls_backend_get_default_database(). - * - * Since: 2.48 - */ - - -/** - * GDtlsConnection:interaction: (nullable) - * - * A #GTlsInteraction object to be used when the connection or certificate - * database need to interact with the user. This will be used to prompt the - * user for passwords where necessary. - * - * Since: 2.48 - */ - - -/** - * GDtlsConnection:negotiated-protocol: - * - * The application-layer protocol negotiated during the TLS - * handshake. See g_dtls_connection_get_negotiated_protocol(). - * - * Since: 2.60 - */ - - -/** - * GDtlsConnection:peer-certificate: (nullable) - * - * The connection's peer's certificate, after the TLS handshake has - * completed or failed. Note in particular that this is not yet set - * during the emission of #GDtlsConnection::accept-certificate. - * - * (You can watch for a #GObject::notify signal on this property to - * detect when a handshake has occurred.) - * - * Since: 2.48 - */ - - -/** - * GDtlsConnection:peer-certificate-errors: - * - * The errors noticed while verifying - * #GDtlsConnection:peer-certificate. Normally this should be 0, but - * it may not be if #GDtlsClientConnection:validation-flags is not - * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if - * #GDtlsConnection::accept-certificate overrode the default - * behavior. - * - * Since: 2.48 - */ - - -/** - * GDtlsConnection:protocol-version: - * - * The DTLS protocol version in use. See g_dtls_connection_get_protocol_version(). - * - * Since: 2.70 - */ - - -/** - * GDtlsConnection:rehandshake-mode: - * - * The rehandshaking mode. See - * g_dtls_connection_set_rehandshake_mode(). - * - * Since: 2.48 - * Deprecated: 2.60: The rehandshake mode is ignored. - */ - - -/** - * GDtlsConnection:require-close-notify: - * - * Whether or not proper TLS close notification is required. - * See g_dtls_connection_set_require_close_notify(). - * - * Since: 2.48 - */ - - -/** - * GDtlsServerConnection:authentication-mode: - * - * The #GTlsAuthenticationMode for the server. This can be changed - * before calling g_dtls_connection_handshake() if you want to - * rehandshake with a different mode from the initial handshake. - * - * Since: 2.48 - */ - - -/** - * GFileIcon:file: - * - * The file containing the icon. - */ - - -/** - * GFileMonitor::changed: - * @monitor: a #GFileMonitor. - * @file: a #GFile. - * @other_file: (nullable): a #GFile or #NULL. - * @event_type: a #GFileMonitorEvent. - * - * Emitted when @file has been changed. - * - * If using %G_FILE_MONITOR_WATCH_MOVES on a directory monitor, and - * the information is available (and if supported by the backend), - * @event_type may be %G_FILE_MONITOR_EVENT_RENAMED, - * %G_FILE_MONITOR_EVENT_MOVED_IN or %G_FILE_MONITOR_EVENT_MOVED_OUT. - * - * In all cases @file will be a child of the monitored directory. For - * renames, @file will be the old name and @other_file is the new - * name. For "moved in" events, @file is the name of the file that - * appeared and @other_file is the old name that it was moved from (in - * another directory). For "moved out" events, @file is the name of - * the file that used to be in this directory and @other_file is the - * name of the file at its new location. - * - * It makes sense to treat %G_FILE_MONITOR_EVENT_MOVED_IN as - * equivalent to %G_FILE_MONITOR_EVENT_CREATED and - * %G_FILE_MONITOR_EVENT_MOVED_OUT as equivalent to - * %G_FILE_MONITOR_EVENT_DELETED, with extra information. - * %G_FILE_MONITOR_EVENT_RENAMED is equivalent to a delete/create - * pair. This is exactly how the events will be reported in the case - * that the %G_FILE_MONITOR_WATCH_MOVES flag is not in use. - * - * If using the deprecated flag %G_FILE_MONITOR_SEND_MOVED flag and @event_type is - * #G_FILE_MONITOR_EVENT_MOVED, @file will be set to a #GFile containing the - * old path, and @other_file will be set to a #GFile containing the new path. - * - * In all the other cases, @other_file will be set to #NULL. - */ - - -/** - * GFilenameCompleter::got-completion-data: - * - * Emitted when the file name completion information comes available. - */ - - -/** - * GIOExtension: - * - * #GIOExtension is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GIOExtensionPoint: - * - * #GIOExtensionPoint is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GIOModuleScope: - * - * Represents a scope for loading IO modules. A scope can be used for blocking - * duplicate modules, or blocking a module you don't want to load. - * - * The scope can be used with g_io_modules_load_all_in_directory_with_scope() - * or g_io_modules_scan_all_in_directory_with_scope(). - * - * Since: 2.30 - */ - - -/** - * GInetAddress: - * - * An IPv4 or IPv6 internet address. - */ - - -/** - * GInetAddress:is-any: - * - * Whether this is the "any" address for its family. - * See g_inet_address_get_is_any(). - * - * Since: 2.22 - */ - - -/** - * GInetAddress:is-link-local: - * - * Whether this is a link-local address. - * See g_inet_address_get_is_link_local(). - * - * Since: 2.22 - */ - - -/** - * GInetAddress:is-loopback: - * - * Whether this is the loopback address for its family. - * See g_inet_address_get_is_loopback(). - * - * Since: 2.22 - */ - - -/** - * GInetAddress:is-mc-global: - * - * Whether this is a global multicast address. - * See g_inet_address_get_is_mc_global(). - * - * Since: 2.22 - */ - - -/** - * GInetAddress:is-mc-link-local: - * - * Whether this is a link-local multicast address. - * See g_inet_address_get_is_mc_link_local(). - * - * Since: 2.22 - */ - - -/** - * GInetAddress:is-mc-node-local: - * - * Whether this is a node-local multicast address. - * See g_inet_address_get_is_mc_node_local(). - * - * Since: 2.22 - */ - - -/** - * GInetAddress:is-mc-org-local: - * - * Whether this is an organization-local multicast address. - * See g_inet_address_get_is_mc_org_local(). - * - * Since: 2.22 - */ - - -/** - * GInetAddress:is-mc-site-local: - * - * Whether this is a site-local multicast address. - * See g_inet_address_get_is_mc_site_local(). - * - * Since: 2.22 - */ - - -/** - * GInetAddress:is-multicast: - * - * Whether this is a multicast address. - * See g_inet_address_get_is_multicast(). - * - * Since: 2.22 - */ - - -/** - * GInetAddress:is-site-local: - * - * Whether this is a site-local address. - * See g_inet_address_get_is_loopback(). - * - * Since: 2.22 - */ - - -/** - * GInetAddressMask: - * - * A combination of an IPv4 or IPv6 base address and a length, - * representing a range of IP addresses. - * - * Since: 2.32 - */ - - -/** - * GInetSocketAddress: - * - * An IPv4 or IPv6 socket address, corresponding to a struct - * sockaddr_in or struct sockaddr_in6. - */ - - -/** - * GInetSocketAddress:flowinfo: - * - * The `sin6_flowinfo` field, for IPv6 addresses. - * - * Since: 2.32 - */ - - -/** - * GInetSocketAddress:scope_id: - * - * The `sin6_scope_id` field, for IPv6 addresses. - * - * Since: 2.32 - */ - - -/** - * GKeyfileSettingsBackend:default-dir: - * - * The directory where the system defaults and locks are located. - * - * Defaults to `/etc/glib-2.0/settings`. - */ - - -/** - * GKeyfileSettingsBackend:filename: - * - * The location where the settings are stored on disk. - * - * Defaults to `$XDG_CONFIG_HOME/glib-2.0/settings/keyfile`. - */ - - -/** - * GKeyfileSettingsBackend:root-group: - * - * If @root_group is non-%NULL then it specifies the name of the keyfile - * group used for keys that are written directly below the root path. - * - * Defaults to NULL. - */ - - -/** - * GKeyfileSettingsBackend:root-path: - * - * All settings read to or written from the backend must fall under the - * path given in @root_path (which must start and end with a slash and - * not contain two consecutive slashes). @root_path may be "/". - * - * Defaults to "/". - */ - - -/** - * GListModel: - * - * #GListModel is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GListModel::items-changed: - * @list: the #GListModel that changed - * @position: the position at which @list changed - * @removed: the number of items removed - * @added: the number of items added - * - * This signal is emitted whenever items were added to or removed - * from @list. At @position, @removed items were removed and @added - * items were added in their place. - * - * Note: If @removed != @added, the positions of all later items - * in the model change. - * - * Since: 2.44 - */ - - -/** - * GListModelInterface: - * @g_iface: parent #GTypeInterface - * @get_item_type: the virtual function pointer for g_list_model_get_item_type() - * @get_n_items: the virtual function pointer for g_list_model_get_n_items() - * @get_item: the virtual function pointer for g_list_model_get_item() - * - * The virtual function table for #GListModel. - * - * Since: 2.44 - */ - - -/** - * GListModelInterface::get_item: - * @list: a #GListModel - * @position: the position of the item to fetch - * - * Get the item at @position. If @position is greater than the number of - * items in @list, %NULL is returned. - * - * %NULL is never returned for an index that is smaller than the length - * of the list. See g_list_model_get_n_items(). - * - * Returns: (type GObject) (transfer full) (nullable): the object at @position. - * Since: 2.44 - */ - - -/** - * GListStore: - * - * #GListStore is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GListStore:item-type: - * - * The type of items contained in this list store. Items must be - * subclasses of #GObject. - * - * Since: 2.44 - */ - - -/** - * GMemoryMonitor: - * - * #GMemoryMonitor monitors system memory and indicates when - * the system is low on memory. - * - * Since: 2.64 - */ - - -/** - * GMemoryMonitor::low-memory-warning: - * @monitor: a #GMemoryMonitor - * @level: the #GMemoryMonitorWarningLevel warning level - * - * Emitted when the system is running low on free memory. The signal - * handler should then take the appropriate action depending on the - * warning level. See the #GMemoryMonitorWarningLevel documentation for - * details. - * - * Since: 2.64 - */ - - -/** - * GMemoryMonitorInterface: - * @g_iface: The parent interface. - * @low_memory_warning: the virtual function pointer for the - * #GMemoryMonitor::low-memory-warning signal. - * - * The virtual function table for #GMemoryMonitor. - * - * Since: 2.64 - */ - - -/** - * GMemoryOutputStream:data: - * - * Pointer to buffer where data will be written. - * - * Since: 2.24 - */ - - -/** - * GMemoryOutputStream:data-size: - * - * Size of data written to the buffer. - * - * Since: 2.24 - */ - - -/** - * GMemoryOutputStream:destroy-function: (skip) - * - * Function called with the buffer as argument when the stream is destroyed. - * - * Since: 2.24 - */ - - -/** - * GMemoryOutputStream:realloc-function: (skip) - * - * Function with realloc semantics called to enlarge the buffer. - * - * Since: 2.24 - */ - - -/** - * GMemoryOutputStream:size: - * - * Current size of the data buffer. - * - * Since: 2.24 - */ - - -/** - * GMenu: - * - * #GMenu is an opaque structure type. You must access it using the - * functions below. - * - * Since: 2.32 - */ - - -/** - * GMenuAttributeIter: - * - * #GMenuAttributeIter is an opaque structure type. You must access it - * using the functions below. - * - * Since: 2.32 - */ - - -/** - * GMenuItem: - * - * #GMenuItem is an opaque structure type. You must access it using the - * functions below. - * - * Since: 2.32 - */ - - -/** - * GMenuLinkIter: - * - * #GMenuLinkIter is an opaque structure type. You must access it using - * the functions below. - * - * Since: 2.32 - */ - - -/** - * GMenuModel: - * - * #GMenuModel is an opaque structure type. You must access it using the - * functions below. - * - * Since: 2.32 - */ - - -/** - * GMenuModel::items-changed: - * @model: the #GMenuModel that is changing - * @position: the position of the change - * @removed: the number of items removed - * @added: the number of items added - * - * Emitted when a change has occurred to the menu. - * - * The only changes that can occur to a menu is that items are removed - * or added. Items may not change (except by being removed and added - * back in the same location). This signal is capable of describing - * both of those changes (at the same time). - * - * The signal means that starting at the index @position, @removed - * items were removed and @added items were added in their place. If - * @removed is zero then only items were added. If @added is zero - * then only items were removed. - * - * As an example, if the menu contains items a, b, c, d (in that - * order) and the signal (2, 1, 3) occurs then the new composition of - * the menu will be a, b, _, _, _, d (with each _ representing some - * new item). - * - * Signal handlers may query the model (particularly the added items) - * and expect to see the results of the modification that is being - * reported. The signal is emitted after the modification. - */ - - -/** - * GMount::changed: - * @mount: the object on which the signal is emitted - * - * Emitted when the mount has been changed. - */ - - -/** - * GMount::pre-unmount: - * @mount: the object on which the signal is emitted - * - * This signal may be emitted when the #GMount is about to be - * unmounted. - * - * This signal depends on the backend and is only emitted if - * GIO was used to unmount. - * - * Since: 2.22 - */ - - -/** - * GMount::unmounted: - * @mount: the object on which the signal is emitted - * - * This signal is emitted when the #GMount have been - * unmounted. If the recipient is holding references to the - * object they should release them so the object can be - * finalized. - */ - - -/** - * GMountOperation::aborted: - * - * Emitted by the backend when e.g. a device becomes unavailable - * while a mount operation is in progress. - * - * Implementations of GMountOperation should handle this signal - * by dismissing open password dialogs. - * - * Since: 2.20 - */ - - -/** - * GMountOperation::ask-password: - * @op: a #GMountOperation requesting a password. - * @message: string containing a message to display to the user. - * @default_user: string containing the default user name. - * @default_domain: string containing the default domain. - * @flags: a set of #GAskPasswordFlags. - * - * Emitted when a mount operation asks the user for a password. - * - * If the message contains a line break, the first line should be - * presented as a heading. For example, it may be used as the - * primary text in a #GtkMessageDialog. - */ - - -/** - * GMountOperation::ask-question: - * @op: a #GMountOperation asking a question. - * @message: string containing a message to display to the user. - * @choices: an array of strings for each possible choice. - * - * Emitted when asking the user a question and gives a list of - * choices for the user to choose from. - * - * If the message contains a line break, the first line should be - * presented as a heading. For example, it may be used as the - * primary text in a #GtkMessageDialog. - */ - - -/** - * GMountOperation::reply: - * @op: a #GMountOperation. - * @result: a #GMountOperationResult indicating how the request was handled - * - * Emitted when the user has replied to the mount operation. - */ - - -/** - * GMountOperation::show-processes: - * @op: a #GMountOperation. - * @message: string containing a message to display to the user. - * @processes: (element-type GPid): an array of #GPid for processes - * blocking the operation. - * @choices: an array of strings for each possible choice. - * - * Emitted when one or more processes are blocking an operation - * e.g. unmounting/ejecting a #GMount or stopping a #GDrive. - * - * Note that this signal may be emitted several times to update the - * list of blocking processes as processes close files. The - * application should only respond with g_mount_operation_reply() to - * the latest signal (setting #GMountOperation:choice to the choice - * the user made). - * - * If the message contains a line break, the first line should be - * presented as a heading. For example, it may be used as the - * primary text in a #GtkMessageDialog. - * - * Since: 2.22 - */ - - -/** - * GMountOperation::show-unmount-progress: - * @op: a #GMountOperation: - * @message: string containing a message to display to the user - * @time_left: the estimated time left before the operation completes, - * in microseconds, or -1 - * @bytes_left: the amount of bytes to be written before the operation - * completes (or -1 if such amount is not known), or zero if the operation - * is completed - * - * Emitted when an unmount operation has been busy for more than some time - * (typically 1.5 seconds). - * - * When unmounting or ejecting a volume, the kernel might need to flush - * pending data in its buffers to the volume stable storage, and this operation - * can take a considerable amount of time. This signal may be emitted several - * times as long as the unmount operation is outstanding, and then one - * last time when the operation is completed, with @bytes_left set to zero. - * - * Implementations of GMountOperation should handle this signal by - * showing an UI notification, and then dismiss it, or show another notification - * of completion, when @bytes_left reaches zero. - * - * If the message contains a line break, the first line should be - * presented as a heading. For example, it may be used as the - * primary text in a #GtkMessageDialog. - * - * Since: 2.34 - */ - - -/** - * GMountOperation:anonymous: - * - * Whether to use an anonymous user when authenticating. - */ - - -/** - * GMountOperation:choice: - * - * The index of the user's choice when a question is asked during the - * mount operation. See the #GMountOperation::ask-question signal. - */ - - -/** - * GMountOperation:domain: - * - * The domain to use for the mount operation. - */ - - -/** - * GMountOperation:is-tcrypt-hidden-volume: - * - * Whether the device to be unlocked is a TCRYPT hidden volume. - * See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Hidden%20Volume.html). - * - * Since: 2.58 - */ - - -/** - * GMountOperation:is-tcrypt-system-volume: - * - * Whether the device to be unlocked is a TCRYPT system volume. - * In this context, a system volume is a volume with a bootloader - * and operating system installed. This is only supported for Windows - * operating systems. For further documentation, see - * [the VeraCrypt documentation](https://www.veracrypt.fr/en/System%20Encryption.html). - * - * Since: 2.58 - */ - - -/** - * GMountOperation:password: - * - * The password that is used for authentication when carrying out - * the mount operation. - */ - - -/** - * GMountOperation:password-save: - * - * Determines if and how the password information should be saved. - */ - - -/** - * GMountOperation:pim: - * - * The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See - * [the VeraCrypt documentation](https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20(PIM).html). - * - * Since: 2.58 - */ - - -/** - * GMountOperation:username: - * - * The user name that is used for authentication when carrying out - * the mount operation. - */ - - -/** - * GNativeSocketAddress: - * - * A socket address, corresponding to a general struct - * sockadd address of a type not otherwise handled by glib. - */ - - -/** - * GNetworkAddress: - * - * A #GSocketConnectable for resolving a hostname and connecting to - * that host. - */ - - -/** - * GNetworkMonitor: - * - * #GNetworkMonitor monitors the status of network connections and - * indicates when a possibly-user-visible change has occurred. - * - * Since: 2.32 - */ - - -/** - * GNetworkMonitor::network-changed: - * @monitor: a #GNetworkMonitor - * @network_available: the current value of #GNetworkMonitor:network-available - * - * Emitted when the network configuration changes. - * - * Since: 2.32 - */ - - -/** - * GNetworkMonitor:connectivity: - * - * More detailed information about the host's network connectivity. - * See g_network_monitor_get_connectivity() and - * #GNetworkConnectivity for more details. - * - * Since: 2.44 - */ - - -/** - * GNetworkMonitor:network-available: - * - * Whether the network is considered available. That is, whether the - * system has a default route for at least one of IPv4 or IPv6. - * - * Real-world networks are of course much more complicated than - * this; the machine may be connected to a wifi hotspot that - * requires payment before allowing traffic through, or may be - * connected to a functioning router that has lost its own upstream - * connectivity. Some hosts might only be accessible when a VPN is - * active. Other hosts might only be accessible when the VPN is - * not active. Thus, it is best to use g_network_monitor_can_reach() - * or g_network_monitor_can_reach_async() to test for reachability - * on a host-by-host basis. (On the other hand, when the property is - * %FALSE, the application can reasonably expect that no remote - * hosts at all are reachable, and should indicate this to the user - * in its UI.) - * - * See also #GNetworkMonitor::network-changed. - * - * Since: 2.32 - */ - - -/** - * GNetworkMonitor:network-metered: - * - * Whether the network is considered metered. That is, whether the - * system has traffic flowing through the default connection that is - * subject to limitations set by service providers. For example, traffic - * might be billed by the amount of data transmitted, or there might be a - * quota on the amount of traffic per month. This is typical with tethered - * connections (3G and 4G) and in such situations, bandwidth intensive - * applications may wish to avoid network activity where possible if it will - * cost the user money or use up their limited quota. - * - * If more information is required about specific devices then the - * system network management API should be used instead (for example, - * NetworkManager or ConnMan). - * - * If this information is not available then no networks will be - * marked as metered. - * - * See also #GNetworkMonitor:network-available. - * - * Since: 2.46 - */ - - -/** - * GNetworkMonitorInterface: - * @g_iface: The parent interface. - * @network_changed: the virtual function pointer for the - * GNetworkMonitor::network-changed signal. - * @can_reach: the virtual function pointer for g_network_monitor_can_reach() - * @can_reach_async: the virtual function pointer for - * g_network_monitor_can_reach_async() - * @can_reach_finish: the virtual function pointer for - * g_network_monitor_can_reach_finish() - * - * The virtual function table for #GNetworkMonitor. - * - * Since: 2.32 - */ - - -/** - * GNetworkService: - * - * A #GSocketConnectable for resolving a SRV record and connecting to - * that service. - */ - - -/** - * GNotification: - * - * This structure type is private and should only be accessed using the - * public APIs. - * - * Since: 2.40 - */ - - -/** - * GPermission: - * - * #GPermission is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GPermission:allowed: - * - * %TRUE if the caller currently has permission to perform the action that - * @permission represents the permission to perform. - */ - - -/** - * GPermission:can-acquire: - * - * %TRUE if it is generally possible to acquire the permission by calling - * g_permission_acquire(). - */ - - -/** - * GPermission:can-release: - * - * %TRUE if it is generally possible to release the permission by calling - * g_permission_release(). - */ - - -/** - * GPowerProfileMonitor: - * - * #GPowerProfileMonitor monitors system power profile and notifies on - * changes. - * - * Since: 2.70 - */ - - -/** - * GPowerProfileMonitor:power-saver-enabled: - * - * Whether “Power Saver” mode is enabled on the system. - * - * Since: 2.70 - */ - - -/** - * GPowerProfileMonitorInterface: - * @g_iface: The parent interface. - * - * The virtual function table for #GPowerProfileMonitor. - * - * Since: 2.70 - */ - - -/** - * 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:invert-boolean: - * - * If %TRUE, the state of the action will be the negation of the - * property value, provided the property is boolean. - * - * Since: 2.46 - */ - - -/** - * 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 - * - * Since: 2.26 - */ - - -/** - * GProxyAddress:destination-protocol: - * - * The protocol being spoke to the destination host, or %NULL if - * the #GProxyAddress doesn't know. - * - * Since: 2.34 - */ - - -/** - * GProxyAddress:uri: - * - * The URI string that the proxy was constructed from (or %NULL - * if the creator didn't specify this). - * - * Since: 2.34 - */ - - -/** - * GProxyAddressClass: - * - * Class structure for #GProxyAddress. - * - * Since: 2.26 - */ - - -/** - * 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 - */ - - -/** - * GProxyResolverInterface: - * @g_iface: The parent interface. - * @is_supported: the virtual function pointer for g_proxy_resolver_is_supported() - * @lookup: the virtual function pointer for g_proxy_resolver_lookup() - * @lookup_async: the virtual function pointer for - * g_proxy_resolver_lookup_async() - * @lookup_finish: the virtual function pointer for - * g_proxy_resolver_lookup_finish() - * - * The virtual function table for #GProxyResolver. - */ - - -/** - * GRemoteActionGroup: - * - * #GRemoteActionGroup is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * 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() - * - * The virtual function table for #GRemoteActionGroup. - * - * Since: 2.32 - */ - - -/** - * GResolver: - * - * The object that handles DNS resolution. Use g_resolver_get_default() - * to get the default resolver. - * - * This is an abstract type; subclasses of it implement different resolvers for - * different platforms and situations. - */ - - -/** - * GResolver::reload: - * @resolver: a #GResolver - * - * Emitted when the resolver notices that the system resolver - * configuration has changed. - */ - - -/** - * GSettings: - * - * #GSettings is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GSettings::change-event: - * @settings: the object on which the signal was emitted - * @keys: (array length=n_keys) (element-type GQuark) (nullable): - * an array of #GQuarks for the changed keys, or %NULL - * @n_keys: the length of the @keys array, or 0 - * - * The "change-event" signal is emitted once per change event that - * affects this settings object. You should connect to this signal - * only if you are interested in viewing groups of changes before they - * are split out into multiple emissions of the "changed" signal. - * For most use cases it is more appropriate to use the "changed" signal. - * - * In the event that the change event applies to one or more specified - * keys, @keys will be an array of #GQuark of length @n_keys. In the - * event that the change event applies to the #GSettings object as a - * whole (ie: potentially every key has been changed) then @keys will - * be %NULL and @n_keys will be 0. - * - * The default handler for this signal invokes the "changed" signal - * for each affected key. If any other connected handler returns - * %TRUE then this default functionality will be suppressed. - * - * Returns: %TRUE to stop other handlers from being invoked for the - * event. FALSE to propagate the event further. - */ - - -/** - * GSettings::changed: - * @settings: the object on which the signal was emitted - * @key: the name of the key that changed - * - * The "changed" signal is emitted when a key has potentially changed. - * You should call one of the g_settings_get() calls to check the new - * value. - * - * This signal supports detailed connections. You can connect to the - * detailed signal "changed::x" in order to only receive callbacks - * when key "x" changes. - * - * Note that @settings only emits this signal if you have read @key at - * least once while a signal handler was already connected for @key. - */ - - -/** - * GSettings::writable-change-event: - * @settings: the object on which the signal was emitted - * @key: the quark of the key, or 0 - * - * The "writable-change-event" signal is emitted once per writability - * change event that affects this settings object. You should connect - * to this signal if you are interested in viewing groups of changes - * before they are split out into multiple emissions of the - * "writable-changed" signal. For most use cases it is more - * appropriate to use the "writable-changed" signal. - * - * In the event that the writability change applies only to a single - * key, @key will be set to the #GQuark for that key. In the event - * that the writability change affects the entire settings object, - * @key will be 0. - * - * The default handler for this signal invokes the "writable-changed" - * and "changed" signals for each affected key. This is done because - * changes in writability might also imply changes in value (if for - * example, a new mandatory setting is introduced). If any other - * connected handler returns %TRUE then this default functionality - * will be suppressed. - * - * Returns: %TRUE to stop other handlers from being invoked for the - * event. FALSE to propagate the event further. - */ - - -/** - * GSettings::writable-changed: - * @settings: the object on which the signal was emitted - * @key: the key - * - * The "writable-changed" signal is emitted when the writability of a - * key has potentially changed. You should call - * g_settings_is_writable() in order to determine the new status. - * - * This signal supports detailed connections. You can connect to the - * detailed signal "writable-changed::x" in order to only receive - * callbacks when the writability of "x" changes. - */ - - -/** - * GSettings:backend: - * - * The name of the context that the settings are stored in. - */ - - -/** - * GSettings:delay-apply: - * - * Whether the #GSettings object is in 'delay-apply' mode. See - * g_settings_delay() for details. - * - * Since: 2.28 - */ - - -/** - * GSettings:has-unapplied: - * - * If this property is %TRUE, the #GSettings object has outstanding - * changes that will be applied when g_settings_apply() is called. - */ - - -/** - * GSettings:path: - * - * The path within the backend where the settings are stored. - */ - - -/** - * GSettings:schema: - * - * The name of the schema that describes the types of keys - * for this #GSettings object. - * - * The type of this property is *not* #GSettingsSchema. - * #GSettingsSchema has only existed since version 2.32 and - * unfortunately this name was used in previous versions to refer to - * the schema ID rather than the schema itself. Take care to use the - * 'settings-schema' property if you wish to pass in a - * #GSettingsSchema. - * - * Deprecated: 2.32: Use the 'schema-id' property instead. In a future - * version, this property may instead refer to a #GSettingsSchema. - */ - - -/** - * GSettings:schema-id: - * - * The name of the schema that describes the types of keys - * for this #GSettings object. - */ - - -/** - * GSettings:settings-schema: - * - * The #GSettingsSchema describing the types of keys for this - * #GSettings object. - * - * Ideally, this property would be called 'schema'. #GSettingsSchema - * has only existed since version 2.32, however, and before then the - * 'schema' property was used to refer to the ID of the schema rather - * than the schema itself. Take care. - */ - - -/** - * GSettingsSchema: - * - * This is an opaque structure type. You may not access it directly. - * - * Since: 2.32 - */ - - -/** - * GSettingsSchemaKey: - * - * #GSettingsSchemaKey is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GSettingsSchemaSource: - * - * This is an opaque structure type. You may not access it directly. - * - * Since: 2.32 - */ - - -/** - * GSimpleAction: - * - * #GSimpleAction is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GSimpleAction::activate: - * @simple: the #GSimpleAction - * @parameter: (nullable): the parameter to the activation, or %NULL if it has - * no parameter - * - * Indicates that the action was just activated. - * - * @parameter will always be of the expected type, i.e. the parameter type - * specified when the action was created. If an incorrect type is given when - * activating the action, this signal is not emitted. - * - * Since GLib 2.40, if no handler is connected to this signal then the - * default behaviour for boolean-stated actions with a %NULL parameter - * type is to toggle them via the #GSimpleAction::change-state signal. - * For stateful actions where the state type is equal to the parameter - * type, the default is to forward them directly to - * #GSimpleAction::change-state. This should allow almost all users - * of #GSimpleAction to connect only one handler or the other. - * - * Since: 2.28 - */ - - -/** - * GSimpleAction::change-state: - * @simple: the #GSimpleAction - * @value: (nullable): the requested value for the state - * - * Indicates that the action just received a request to change its - * state. - * - * @value will always be of the correct state type, i.e. the type of the - * initial state passed to g_simple_action_new_stateful(). If an incorrect - * type is given when requesting to change the state, this signal is not - * emitted. - * - * If no handler is connected to this signal then the default - * behaviour is to call g_simple_action_set_state() to set the state - * to the requested value. If you connect a signal handler then no - * default action is taken. If the state should change then you must - * call g_simple_action_set_state() from the handler. - * - * An example of a 'change-state' handler: - * |[ - * static void - * change_volume_state (GSimpleAction *action, - * GVariant *value, - * gpointer user_data) - * { - * gint requested; - * - * requested = g_variant_get_int32 (value); - * - * // Volume only goes from 0 to 10 - * if (0 <= requested && requested <= 10) - * g_simple_action_set_state (action, value); - * } - * ]| - * - * The handler need not set the state to the requested value. - * It could set it to any value at all, or take some other action. - * - * Since: 2.30 - */ - - -/** - * GSimpleAction: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.28 - */ - - -/** - * GSimpleAction:name: - * - * The name of the action. This is mostly meaningful for identifying - * the action once it has been added to a #GSimpleActionGroup. - * - * Since: 2.28 - */ - - -/** - * GSimpleAction:parameter-type: - * - * The type of the parameter that must be given when activating the - * action. - * - * Since: 2.28 - */ - - -/** - * GSimpleAction:state: - * - * The state of the action, or %NULL if the action is stateless. - * - * Since: 2.28 - */ - - -/** - * GSimpleAction:state-type: - * - * The #GVariantType of the state that the action has, or %NULL if the - * action is stateless. - * - * Since: 2.28 - */ - - -/** - * GSimpleIOStream: - * - * A wrapper around a #GInputStream and a #GOutputStream. - * - * Since: 2.44 - */ - - -/** - * GSimpleIOStream:input-stream: - * - * Since: 2.44 - */ - - -/** - * GSimpleIOStream:output-stream: - * - * Since: 2.44 - */ - - -/** - * GSimplePermission: - * - * #GSimplePermission is an opaque data structure. There are no methods - * except for those defined by #GPermission. - */ - - -/** - * 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 - * "socks://", #GSimpleProxyResolver will treat it as referring - * to all three of the socks5, socks4a, and socks4 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: - * - * - A hostname, such as "example.com", ".example.com", or - * "*.example.com", any of which match "example.com" or - * any subdomain of it. - * - * - An IPv4 or IPv6 address, such as "192.168.1.1", - * which matches only that address. - * - * - A hostname or IP address followed by a port, such as - * "example.com:80", 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: "[::1]:443" - * - * - An IP address range, given by a base address and prefix length, - * such as "fe80::/10", which matches any address in that range. - * - * 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 - * example.com has an address of 192.168.1.1, and the :ignore-hosts list - * contains only "192.168.1.1", then a connection to "example.com" - * (eg, via a #GNetworkAddress) will use the proxy, and a connection to - * "192.168.1.1" (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 broadcast addresses. - * - * Since: 2.32 - */ - - -/** - * GSocket:multicast-loopback: - * - * Whether outgoing multicast packets loop back to the local host. - * - * Since: 2.32 - */ - - -/** - * GSocket:multicast-ttl: - * - * Time-to-live out outgoing multicast packets - * - * Since: 2.32 - */ - - -/** - * GSocket:timeout: - * - * The timeout in seconds on socket I/O - * - * Since: 2.26 - */ - - -/** - * GSocket:ttl: - * - * Time-to-live for outgoing unicast packets - * - * Since: 2.32 - */ - - -/** - * GSocketAddress: - * - * A socket endpoint address, corresponding to struct sockaddr - * or one of its subtypes. - */ - - -/** - * GSocketClient::event: - * @client: the #GSocketClient - * @event: the event that is occurring - * @connectable: the #GSocketConnectable that @event is occurring on - * @connection: (nullable): the current representation of the connection - * - * Emitted when @client's activity on @connectable changes state. - * Among other things, this can be used to provide progress - * information about a network connection in the UI. The meanings of - * the different @event values are as follows: - * - * - %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable - * in DNS. @connection will be %NULL. - * - * - %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved - * @connectable in DNS. @connection will be %NULL. - * - * - %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection - * to a remote host; either a proxy server or the destination server - * itself. @connection is the #GSocketConnection, which is not yet - * connected. Since GLib 2.40, you can access the remote - * address via g_socket_connection_get_remote_address(). - * - * - %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected - * to a remote host. @connection is the connected #GSocketConnection. - * - * - %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate - * with a proxy to get it to connect to @connectable. @connection is - * the #GSocketConnection to the proxy server. - * - * - %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a - * connection to @connectable through a proxy server. @connection is - * the stream returned from g_proxy_connect(), which may or may not - * be a #GSocketConnection. - * - * - %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS - * handshake. @connection is a #GTlsClientConnection. - * - * - %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed - * the TLS handshake. @connection is a #GTlsClientConnection. - * - * - %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected - * to @connectable (in which case @connection is the #GSocketConnection - * that it will be returning to the caller) or has failed (in which - * case @connection is %NULL and the client is about to return an error). - * - * Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted - * multiple times (or not at all) for a given connectable (in - * particular, if @client ends up attempting to connect to more than - * one address). However, if @client emits the #GSocketClient::event - * signal at all for a given connectable, then it will always emit - * it with %G_SOCKET_CLIENT_COMPLETE when it is done. - * - * Note that there may be additional #GSocketClientEvent values in - * the future; unrecognized @event values should be ignored. - * - * Since: 2.32 - */ - - -/** - * GSocketClient:proxy-resolver: - * - * The proxy resolver to use - * - * Since: 2.36 - */ - - -/** - * GSocketListener::event: - * @listener: the #GSocketListener - * @event: the event that is occurring - * @socket: the #GSocket the event is occurring on - * - * Emitted when @listener's activity on @socket changes state. - * Note that when @listener is used to listen on both IPv4 and - * IPv6, a separate set of signals will be emitted for each, and - * the order they happen in is undefined. - * - * Since: 2.46 - */ - - -/** - * GSocketService::incoming: - * @service: the #GSocketService - * @connection: a new #GSocketConnection object - * @source_object: (nullable): the source_object passed to - * g_socket_listener_add_address() - * - * The ::incoming signal is emitted when a new incoming connection - * to @service needs to be handled. The handler must initiate the - * handling of @connection, but may not block; in essence, - * asynchronous operations must be used. - * - * @connection will be unreffed once the signal handler returns, - * so you need to ref it yourself if you are planning to use it. - * - * Returns: %TRUE to stop other handlers from being called - * Since: 2.22 - */ - - -/** - * GSocketService:active: - * - * Whether the service is currently accepting connections. - * - * Since: 2.46 - */ - - -/** - * GSrvTarget: - * - * A single target host/port that a network service is running on. - */ - - -/** - * GStaticResource: - * - * #GStaticResource is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GTask: - * - * The opaque object representing a synchronous or asynchronous task - * and its result. - */ - - -/** - * GTask:completed: - * - * Whether the task has completed, meaning its callback (if set) has been - * invoked. This can only happen after g_task_return_pointer(), - * g_task_return_error() or one of the other return functions have been called - * on the task. - * - * This property is guaranteed to change from %FALSE to %TRUE exactly once. - * - * The #GObject::notify signal for this change is emitted in the same main - * context as the task’s callback, immediately after that callback is invoked. - * - * Since: 2.44 - */ - - -/** - * 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, not when it calls a - * `g_task_return_` function. - * - * Since: 2.36 - */ - - -/** - * GTcpWrapperConnection: - * - * #GTcpWrapperConnection is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GTestDBus: - * - * The #GTestDBus structure contains only private data and - * should only be accessed using the provided API. - * - * Since: 2.34 - */ - - -/** - * GTestDBus:flags: - * - * #GTestDBusFlags specifying the behaviour of the D-Bus session. - * - * Since: 2.34 - */ - - -/** - * GThemedIcon:name: - * - * The icon name. - */ - - -/** - * GThemedIcon:names: - * - * A %NULL-terminated array of icon names. - */ - - -/** - * GThemedIcon:use-default-fallbacks: - * - * Whether to use the default fallbacks found by shortening the icon name - * at '-' characters. If the "names" array has more than one element, - * ignores any past the first. - * - * For example, if the icon name was "gnome-dev-cdrom-audio", the array - * would become - * |[ - * { - * "gnome-dev-cdrom-audio", - * "gnome-dev-cdrom", - * "gnome-dev", - * "gnome", - * NULL - * }; - * ]| - */ - - -/** - * GThreadedSocketService::run: - * @service: the #GThreadedSocketService. - * @connection: a new #GSocketConnection object. - * @source_object: (nullable): the source_object passed to g_socket_listener_add_address(). - * - * The ::run signal is emitted in a worker thread in response to an - * incoming connection. This thread is dedicated to handling - * @connection and may perform blocking IO. The signal handler need - * not return until the connection is closed. - * - * Returns: %TRUE to stop further signal handlers from being called - */ - - -/** - * GTlsBackend: - * - * TLS (Transport Layer Security, aka SSL) and DTLS backend. This is an - * internal type used to coordinate the different classes implemented - * by a TLS backend. - * - * Since: 2.28 - */ - - -/** - * GTlsCertificate: - * - * Abstract base class for TLS certificate types. - * - * Since: 2.28 - */ - - -/** - * GTlsCertificate:certificate: - * - * The DER (binary) encoded representation of the certificate. - * This property and the #GTlsCertificate:certificate-pem property - * represent the same data, just in different forms. - * - * Since: 2.28 - */ - - -/** - * GTlsCertificate:certificate-pem: - * - * The PEM (ASCII) encoded representation of the certificate. - * This property and the #GTlsCertificate:certificate - * property represent the same data, just in different forms. - * - * Since: 2.28 - */ - - -/** - * GTlsCertificate:dns-names: (nullable) (element-type GBytes) (transfer container) - * - * The DNS names from the certificate's Subject Alternative Names (SANs), - * %NULL if unavailable. - * - * Since: 2.70 - */ - - -/** - * GTlsCertificate:ip-addresses: (nullable) (element-type GInetAddress) (transfer container) - * - * The IP addresses from the certificate's Subject Alternative Names (SANs), - * %NULL if unavailable. - * - * Since: 2.70 - */ - - -/** - * GTlsCertificate:issuer: - * - * A #GTlsCertificate representing the entity that issued this - * certificate. If %NULL, this means that the certificate is either - * self-signed, or else the certificate of the issuer is not - * available. - * - * Beware the issuer certificate may not be the same as the - * certificate that would actually be used to construct a valid - * certification path during certificate verification. - * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains - * why an issuer certificate cannot be naively assumed to be part of the - * the certification path (though GLib's TLS backends may not follow the - * path building strategies outlined in this RFC). Due to the complexity - * of certification path building, GLib does not provide any way to know - * which certification path will actually be used. Accordingly, this - * property cannot be used to make security-related decisions. Only - * GLib itself should make security decisions about TLS certificates. - * - * Since: 2.28 - */ - - -/** - * GTlsCertificate:issuer-name: (nullable) - * - * The issuer from the certificate, - * %NULL if unavailable. - * - * Since: 2.70 - */ - - -/** - * GTlsCertificate:not-valid-after: (nullable) - * - * The time at which this cert is no longer valid, - * %NULL if unavailable. - * - * Since: 2.70 - */ - - -/** - * GTlsCertificate:not-valid-before: (nullable) - * - * The time at which this cert is considered to be valid, - * %NULL if unavailable. - * - * Since: 2.70 - */ - - -/** - * GTlsCertificate:pkcs11-uri: (nullable) - * - * A URI referencing the [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) - * objects containing an X.509 certificate and optionally a private key. - * - * If %NULL, the certificate is either not backed by PKCS \#11 or the - * #GTlsBackend does not support PKCS \#11. - * - * Since: 2.68 - */ - - -/** - * GTlsCertificate:private-key: (nullable) - * - * The DER (binary) encoded representation of the certificate's - * private key, in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) - * or unencrypted [PKCS \#8 format.](https://datatracker.ietf.org/doc/html/rfc5208) - * PKCS \#8 format is supported since 2.32; earlier releases only - * support PKCS \#1. You can use the `openssl rsa` tool to convert - * PKCS \#8 keys to PKCS \#1. - * - * This property (or the #GTlsCertificate:private-key-pem property) - * can be set when constructing a key (for example, from a file). - * Since GLib 2.70, it is now also readable; however, be aware that if - * the private key is backed by a PKCS \#11 URI – for example, if it - * is stored on a smartcard – then this property will be %NULL. If so, - * the private key must be referenced via its PKCS \#11 URI, - * #GTlsCertificate:private-key-pkcs11-uri. You must check both - * properties to see if the certificate really has a private key. - * When this property is read, the output format will be unencrypted - * PKCS \#8. - * - * Since: 2.28 - */ - - -/** - * GTlsCertificate:private-key-pem: (nullable) - * - * The PEM (ASCII) encoded representation of the certificate's - * private key in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) - * ("`BEGIN RSA PRIVATE KEY`") or unencrypted - * [PKCS \#8 format](https://datatracker.ietf.org/doc/html/rfc5208) - * ("`BEGIN PRIVATE KEY`"). PKCS \#8 format is supported since 2.32; - * earlier releases only support PKCS \#1. You can use the `openssl rsa` - * tool to convert PKCS \#8 keys to PKCS \#1. - * - * This property (or the #GTlsCertificate:private-key property) - * can be set when constructing a key (for example, from a file). - * Since GLib 2.70, it is now also readable; however, be aware that if - * the private key is backed by a PKCS \#11 URI - for example, if it - * is stored on a smartcard - then this property will be %NULL. If so, - * the private key must be referenced via its PKCS \#11 URI, - * #GTlsCertificate:private-key-pkcs11-uri. You must check both - * properties to see if the certificate really has a private key. - * When this property is read, the output format will be unencrypted - * PKCS \#8. - * - * Since: 2.28 - */ - - -/** - * GTlsCertificate:private-key-pkcs11-uri: (nullable) - * - * A URI referencing a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) - * object containing a private key. - * - * Since: 2.68 - */ - - -/** - * GTlsCertificate:subject-name: (nullable) - * - * The subject from the cert, - * %NULL if unavailable. - * - * Since: 2.70 - */ - - -/** - * GTlsClientConnection: - * - * Abstract base class for the backend-specific client connection - * type. - * - * Since: 2.28 - */ - - -/** - * GTlsClientConnection:accepted-cas: (type GLib.List) (element-type GLib.ByteArray) - * - * A list of the distinguished names of the Certificate Authorities - * that the server will accept client certificates signed by. If the - * server requests a client certificate during the handshake, then - * this property will be set after the handshake completes. - * - * Each item in the list is a #GByteArray which contains the complete - * subject DN of the certificate authority. - * - * Since: 2.28 - */ - - -/** - * GTlsClientConnection:server-identity: - * - * A #GSocketConnectable describing the identity of the server that - * is expected on the other end of the connection. - * - * If the %G_TLS_CERTIFICATE_BAD_IDENTITY flag is set in - * #GTlsClientConnection:validation-flags, this object will be used - * to determine the expected identify of the remote end of the - * connection; if #GTlsClientConnection:server-identity is not set, - * or does not match the identity presented by the server, then the - * %G_TLS_CERTIFICATE_BAD_IDENTITY validation will fail. - * - * In addition to its use in verifying the server certificate, - * this is also used to give a hint to the server about what - * certificate we expect, which is useful for servers that serve - * virtual hosts. - * - * Since: 2.28 - */ - - -/** - * GTlsClientConnection:use-ssl3: - * - * SSL 3.0 is no longer supported. See - * g_tls_client_connection_set_use_ssl3() for details. - * - * Since: 2.28 - * Deprecated: 2.56: SSL 3.0 is insecure. - */ - - -/** - * GTlsClientConnection:validation-flags: - * - * What steps to perform when validating a certificate received from - * a server. Server certificates that fail to validate in any of the - * ways indicated here will be rejected unless the application - * overrides the default via #GTlsConnection::accept-certificate. - * - * Since: 2.28 - */ - - -/** - * GTlsConnection: - * - * Abstract base class for the backend-specific #GTlsClientConnection - * and #GTlsServerConnection types. - * - * Since: 2.28 - */ - - -/** - * GTlsConnection::accept-certificate: - * @conn: a #GTlsConnection - * @peer_cert: the peer's #GTlsCertificate - * @errors: the problems with @peer_cert. - * - * Emitted during the TLS handshake after the peer certificate has - * been received. You can examine @peer_cert's certification path by - * calling g_tls_certificate_get_issuer() on it. - * - * For a client-side connection, @peer_cert is the server's - * certificate, and the signal will only be emitted if the - * certificate was not acceptable according to @conn's - * #GTlsClientConnection:validation_flags. If you would like the - * certificate to be accepted despite @errors, return %TRUE from the - * signal handler. Otherwise, if no handler accepts the certificate, - * the handshake will fail with %G_TLS_ERROR_BAD_CERTIFICATE. - * - * For a server-side connection, @peer_cert is the certificate - * presented by the client, if this was requested via the server's - * #GTlsServerConnection:authentication_mode. On the server side, - * the signal is always emitted when the client presents a - * certificate, and the certificate will only be accepted if a - * handler returns %TRUE. - * - * Note that if this signal is emitted as part of asynchronous I/O - * in the main thread, then you should not attempt to interact with - * the user before returning from the signal handler. If you want to - * let the user decide whether or not to accept the certificate, you - * would have to return %FALSE from the signal handler on the first - * attempt, and then after the connection attempt returns a - * %G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and - * if the user decides to accept the certificate, remember that fact, - * create a new connection, and return %TRUE from the signal handler - * the next time. - * - * If you are doing I/O in another thread, you do not - * need to worry about this, and can simply block in the signal - * handler until the UI thread returns an answer. - * - * Returns: %TRUE to accept @peer_cert (which will also - * immediately end the signal emission). %FALSE to allow the signal - * emission to continue, which will cause the handshake to fail if - * no one else overrides it. - * Since: 2.28 - */ - - -/** - * GTlsConnection:advertised-protocols: (nullable) - * - * The list of application-layer protocols that the connection - * advertises that it is willing to speak. See - * g_tls_connection_set_advertised_protocols(). - * - * Since: 2.60 - */ - - -/** - * GTlsConnection:base-io-stream: - * - * The #GIOStream that the connection wraps. The connection holds a reference - * to this stream, and may run operations on the stream from other threads - * throughout its lifetime. Consequently, after the #GIOStream has been - * constructed, application code may only run its own operations on this - * stream when no #GIOStream operations are running. - * - * Since: 2.28 - */ - - -/** - * GTlsConnection:certificate: - * - * The connection's certificate; see - * g_tls_connection_set_certificate(). - * - * Since: 2.28 - */ - - -/** - * GTlsConnection:ciphersuite-name: (nullable) - * - * The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name(). - * - * Since: 2.70 - */ - - -/** - * GTlsConnection:database: (nullable) - * - * The certificate database to use when verifying this TLS connection. - * If no certificate database is set, then the default database will be - * used. See g_tls_backend_get_default_database(). - * - * Since: 2.30 - */ - - -/** - * GTlsConnection:interaction: (nullable) - * - * A #GTlsInteraction object to be used when the connection or certificate - * database need to interact with the user. This will be used to prompt the - * user for passwords where necessary. - * - * Since: 2.30 - */ - - -/** - * GTlsConnection:negotiated-protocol: - * - * The application-layer protocol negotiated during the TLS - * handshake. See g_tls_connection_get_negotiated_protocol(). - * - * Since: 2.60 - */ - - -/** - * GTlsConnection:peer-certificate: (nullable) - * - * The connection's peer's certificate, after the TLS handshake has - * completed or failed. Note in particular that this is not yet set - * during the emission of #GTlsConnection::accept-certificate. - * - * (You can watch for a #GObject::notify signal on this property to - * detect when a handshake has occurred.) - * - * Since: 2.28 - */ - - -/** - * GTlsConnection:peer-certificate-errors: - * - * The errors noticed while verifying - * #GTlsConnection:peer-certificate. Normally this should be 0, but - * it may not be if #GTlsClientConnection:validation-flags is not - * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if - * #GTlsConnection::accept-certificate overrode the default - * behavior. - * - * Since: 2.28 - */ - - -/** - * GTlsConnection:protocol-version: - * - * The TLS protocol version in use. See g_tls_connection_get_protocol_version(). - * - * Since: 2.70 - */ - - -/** - * GTlsConnection:rehandshake-mode: - * - * The rehandshaking mode. See - * g_tls_connection_set_rehandshake_mode(). - * - * Since: 2.28 - * Deprecated: 2.60: The rehandshake mode is ignored. - */ - - -/** - * GTlsConnection:require-close-notify: - * - * Whether or not proper TLS close notification is required. - * See g_tls_connection_set_require_close_notify(). - * - * Since: 2.28 - */ - - -/** - * GTlsConnection:use-system-certdb: - * - * Whether or not the system certificate database will be used to - * verify peer certificates. See - * g_tls_connection_set_use_system_certdb(). - * - * Deprecated: 2.30: Use GTlsConnection:database instead - */ - - -/** - * GTlsDatabase: - * - * Abstract base class for the backend-specific database types. - * - * Since: 2.30 - */ - - -/** - * GTlsDatabaseClass: - * @verify_chain: Virtual method implementing - * g_tls_database_verify_chain(). - * @verify_chain_async: Virtual method implementing - * g_tls_database_verify_chain_async(). - * @verify_chain_finish: Virtual method implementing - * g_tls_database_verify_chain_finish(). - * @create_certificate_handle: Virtual method implementing - * g_tls_database_create_certificate_handle(). - * @lookup_certificate_for_handle: Virtual method implementing - * g_tls_database_lookup_certificate_for_handle(). - * @lookup_certificate_for_handle_async: Virtual method implementing - * g_tls_database_lookup_certificate_for_handle_async(). - * @lookup_certificate_for_handle_finish: Virtual method implementing - * g_tls_database_lookup_certificate_for_handle_finish(). - * @lookup_certificate_issuer: Virtual method implementing - * g_tls_database_lookup_certificate_issuer(). - * @lookup_certificate_issuer_async: Virtual method implementing - * g_tls_database_lookup_certificate_issuer_async(). - * @lookup_certificate_issuer_finish: Virtual method implementing - * g_tls_database_lookup_certificate_issuer_finish(). - * @lookup_certificates_issued_by: Virtual method implementing - * g_tls_database_lookup_certificates_issued_by(). - * @lookup_certificates_issued_by_async: Virtual method implementing - * g_tls_database_lookup_certificates_issued_by_async(). - * @lookup_certificates_issued_by_finish: Virtual method implementing - * g_tls_database_lookup_certificates_issued_by_finish(). - * - * The class for #GTlsDatabase. Derived classes should implement the various - * virtual methods. _async and _finish methods have a default - * implementation that runs the corresponding sync method in a thread. - * - * Since: 2.30 - */ - - -/** - * GTlsFileDatabase: - * - * Implemented by a #GTlsDatabase which allows you to load certificates - * from a file. - * - * Since: 2.30 - */ - - -/** - * GTlsFileDatabase:anchors: - * - * The path to a file containing PEM encoded certificate authority - * root anchors. The certificates in this file will be treated as - * root authorities for the purpose of verifying other certificates - * via the g_tls_database_verify_chain() operation. - * - * Since: 2.30 - */ - - -/** - * GTlsInteraction: - * - * An object representing interaction that the TLS connection and database - * might have with the user. - * - * Since: 2.30 - */ - - -/** - * GTlsInteractionClass: - * @ask_password: ask for a password synchronously. If the implementation - * returns %G_TLS_INTERACTION_HANDLED, then the password argument should - * have been filled in by using g_tls_password_set_value() or a similar - * function. - * @ask_password_async: ask for a password asynchronously. - * @ask_password_finish: complete operation to ask for a password asynchronously. - * If the implementation returns %G_TLS_INTERACTION_HANDLED, then the - * password argument of the async method should have been filled in by using - * g_tls_password_set_value() or a similar function. - * @request_certificate: ask for a certificate synchronously. If the - * implementation returns %G_TLS_INTERACTION_HANDLED, then the connection - * argument should have been filled in by using - * g_tls_connection_set_certificate(). - * @request_certificate_async: ask for a certificate asynchronously. - * @request_certificate_finish: complete operation to ask for a certificate - * asynchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, - * then the connection argument of the async method should have been - * filled in by using g_tls_connection_set_certificate(). - * - * The class for #GTlsInteraction. Derived classes implement the various - * virtual interaction methods to handle TLS interactions. - * - * Derived classes can choose to implement whichever interactions methods they'd - * like to support by overriding those virtual methods in their class - * initialization function. If a derived class implements an async method, - * it must also implement the corresponding finish method. - * - * The synchronous interaction methods should implement to display modal dialogs, - * and the asynchronous methods to display modeless dialogs. - * - * If the user cancels an interaction, then the result should be - * %G_TLS_INTERACTION_FAILED and the error should be set with a domain of - * %G_IO_ERROR and code of %G_IO_ERROR_CANCELLED. - * - * Since: 2.30 - */ - - -/** - * GTlsPassword: - * - * An abstract interface representing a password used in TLS. Often used in - * user interaction such as unlocking a key storage token. - * - * Since: 2.30 - */ - - -/** - * GTlsServerConnection:authentication-mode: - * - * The #GTlsAuthenticationMode for the server. This can be changed - * before calling g_tls_connection_handshake() if you want to - * rehandshake with a different mode from the initial handshake. - * - * Since: 2.28 - */ - - -/** - * GUnixConnection: - * - * #GUnixConnection is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GUnixCredentialsMessage:credentials: - * - * The credentials stored in the message. - * - * Since: 2.26 - */ - - -/** - * GUnixFDList: - * - * #GUnixFDList is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GUnixFDMessage: - * - * #GUnixFDMessage is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GUnixInputStream:close-fd: - * - * Whether to close the file descriptor when the stream is closed. - * - * Since: 2.20 - */ - - -/** - * GUnixInputStream:fd: - * - * The file descriptor that the stream reads from. - * - * Since: 2.20 - */ - - -/** - * GUnixMountMonitor::mountpoints-changed: - * @monitor: the object on which the signal is emitted - * - * Emitted when the unix mount points have changed. - */ - - -/** - * GUnixMountMonitor::mounts-changed: - * @monitor: the object on which the signal is emitted - * - * Emitted when the unix mounts have changed. - */ - - -/** - * GUnixMountType: - * @G_UNIX_MOUNT_TYPE_UNKNOWN: Unknown UNIX mount type. - * @G_UNIX_MOUNT_TYPE_FLOPPY: Floppy disk UNIX mount type. - * @G_UNIX_MOUNT_TYPE_CDROM: CDROM UNIX mount type. - * @G_UNIX_MOUNT_TYPE_NFS: Network File System (NFS) UNIX mount type. - * @G_UNIX_MOUNT_TYPE_ZIP: ZIP UNIX mount type. - * @G_UNIX_MOUNT_TYPE_JAZ: JAZZ UNIX mount type. - * @G_UNIX_MOUNT_TYPE_MEMSTICK: Memory Stick UNIX mount type. - * @G_UNIX_MOUNT_TYPE_CF: Compact Flash UNIX mount type. - * @G_UNIX_MOUNT_TYPE_SM: Smart Media UNIX mount type. - * @G_UNIX_MOUNT_TYPE_SDMMC: SD/MMC UNIX mount type. - * @G_UNIX_MOUNT_TYPE_IPOD: iPod UNIX mount type. - * @G_UNIX_MOUNT_TYPE_CAMERA: Digital camera UNIX mount type. - * @G_UNIX_MOUNT_TYPE_HD: Hard drive UNIX mount type. - * - * Types of UNIX mounts. - */ - - -/** - * GUnixOutputStream:close-fd: - * - * Whether to close the file descriptor when the stream is closed. - * - * Since: 2.20 - */ - - -/** - * GUnixOutputStream:fd: - * - * The file descriptor that the stream writes to. - * - * Since: 2.20 - */ - - -/** - * GUnixSocketAddress: - * - * A UNIX-domain (local) socket address, corresponding to a - * struct sockaddr_un. - */ - - -/** - * GUnixSocketAddress:abstract: - * - * Whether or not this is an abstract address - * - * Deprecated: Use #GUnixSocketAddress:address-type, which - * distinguishes between zero-padded and non-zero-padded - * abstract addresses. - */ - - -/** - * GVolume::changed: - * - * Emitted when the volume has been changed. - */ - - -/** - * GVolume::removed: - * - * This signal is emitted when the #GVolume have been removed. If - * the recipient is holding references to the object they should - * release them so the object can be finalized. - */ - - -/** - * GVolumeMonitor::drive-changed: - * @volume_monitor: The volume monitor emitting the signal. - * @drive: the drive that changed - * - * Emitted when a drive changes. - */ - - -/** - * GVolumeMonitor::drive-connected: - * @volume_monitor: The volume monitor emitting the signal. - * @drive: a #GDrive that was connected. - * - * Emitted when a drive is connected to the system. - */ - - -/** - * GVolumeMonitor::drive-disconnected: - * @volume_monitor: The volume monitor emitting the signal. - * @drive: a #GDrive that was disconnected. - * - * Emitted when a drive is disconnected from the system. - */ - - -/** - * GVolumeMonitor::drive-eject-button: - * @volume_monitor: The volume monitor emitting the signal. - * @drive: the drive where the eject button was pressed - * - * Emitted when the eject button is pressed on @drive. - * - * Since: 2.18 - */ - - -/** - * GVolumeMonitor::drive-stop-button: - * @volume_monitor: The volume monitor emitting the signal. - * @drive: the drive where the stop button was pressed - * - * Emitted when the stop button is pressed on @drive. - * - * Since: 2.22 - */ - - -/** - * GVolumeMonitor::mount-added: - * @volume_monitor: The volume monitor emitting the signal. - * @mount: a #GMount that was added. - * - * Emitted when a mount is added. - */ - - -/** - * GVolumeMonitor::mount-changed: - * @volume_monitor: The volume monitor emitting the signal. - * @mount: a #GMount that changed. - * - * Emitted when a mount changes. - */ - - -/** - * GVolumeMonitor::mount-pre-unmount: - * @volume_monitor: The volume monitor emitting the signal. - * @mount: a #GMount that is being unmounted. - * - * May be emitted when a mount is about to be removed. - * - * This signal depends on the backend and is only emitted if - * GIO was used to unmount. - */ - - -/** - * GVolumeMonitor::mount-removed: - * @volume_monitor: The volume monitor emitting the signal. - * @mount: a #GMount that was removed. - * - * Emitted when a mount is removed. - */ - - -/** - * GVolumeMonitor::volume-added: - * @volume_monitor: The volume monitor emitting the signal. - * @volume: a #GVolume that was added. - * - * Emitted when a mountable volume is added to the system. - */ - - -/** - * GVolumeMonitor::volume-changed: - * @volume_monitor: The volume monitor emitting the signal. - * @volume: a #GVolume that changed. - * - * Emitted when mountable volume is changed. - */ - - -/** - * GVolumeMonitor::volume-removed: - * @volume_monitor: The volume monitor emitting the signal. - * @volume: a #GVolume that was removed. - * - * Emitted when a mountable volume is removed from the system. - */ - - -/** - * GWin32InputStream:close-handle: - * - * Whether to close the file handle when the stream is closed. - * - * Since: 2.26 - */ - - -/** - * GWin32InputStream:handle: - * - * The handle that the stream reads from. - * - * Since: 2.26 - */ - - -/** - * GWin32OutputStream:close-handle: - * - * Whether to close the file handle when the stream is closed. - * - * Since: 2.26 - */ - - -/** - * GWin32OutputStream:handle: - * - * The file handle that the stream writes to. - * - * Since: 2.26 - */ - - -/** - * GWin32RegistryKey:path: - * - * A path to the key in the registry, in UTF-8. - * - * Since: 2.46 - */ - - -/** - * GWin32RegistryKey:path-utf16: - * - * A path to the key in the registry, in UTF-16. - * - * Since: 2.46 - */ - - -/** - * GZlibCompressor: - * - * Zlib decompression - */ - - -/** - * GZlibCompressor:file-info: - * - * If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is - * %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name - * and modification time from the file info to the GZIP header. - * - * Since: 2.26 - */ - - -/** - * GZlibDecompressor: - * - * Zlib decompression - */ - - -/** - * GZlibDecompressor:file-info: - * - * A #GFileInfo containing the information found in the GZIP header - * of the data stream processed, or %NULL if the header was not yet - * fully processed, is not present at all, or the compressor's - * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP. - * - * Since: 2.26 - */ - - -/** - * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT: - * - * The purpose used to verify the client certificate in a TLS connection. - * Used by TLS servers. - */ - - -/** - * G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER: - * - * The purpose used to verify the server certificate in a TLS connection. This - * is the most common purpose in use. Used by TLS clients. - */ - - -/** - * G_TYPE_SETTINGS_SCHEMA: - * - * A boxed #GType corresponding to #GSettingsSchema. - * - * Since: 2.32 - */ - - -/** - * G_TYPE_SETTINGS_SCHEMA_SOURCE: - * - * A boxed #GType corresponding to #GSettingsSchemaSource. - * - * Since: 2.32 - */ - - -/** - * SECTION:extensionpoints - * @short_description: Extension Points - * @include: gio.h - * @see_also: [Extending GIO][extending-gio] - * - * #GIOExtensionPoint provides a mechanism for modules to extend the - * functionality of the library or application that loaded it in an - * organized fashion. - * - * An extension point is identified by a name, and it may optionally - * require that any implementation must be of a certain type (or derived - * thereof). Use g_io_extension_point_register() to register an - * extension point, and g_io_extension_point_set_required_type() to - * set a required type. - * - * A module can implement an extension point by specifying the #GType - * that implements the functionality. Additionally, each implementation - * of an extension point has a name, and a priority. Use - * g_io_extension_point_implement() to implement an extension point. - * - * |[ - * GIOExtensionPoint *ep; - * - * // Register an extension point - * ep = g_io_extension_point_register ("my-extension-point"); - * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); - * ]| - * - * |[ - * // Implement an extension point - * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE) - * g_io_extension_point_implement ("my-extension-point", - * my_example_impl_get_type (), - * "my-example", - * 10); - * ]| - * - * It is up to the code that registered the extension point how - * it uses the implementations that have been associated with it. - * Depending on the use case, it may use all implementations, or - * only the one with the highest priority, or pick a specific - * one by name. - * - * To avoid opening all modules just to find out what extension - * points they implement, GIO makes use of a caching mechanism, - * see [gio-querymodules][gio-querymodules]. - * You are expected to run this command after installing a - * GIO module. - * - * The `GIO_EXTRA_MODULES` environment variable can be used to - * specify additional directories to automatically load modules - * from. This environment variable has the same syntax as the - * `PATH`. If two modules have the same base name in different - * directories, then the latter one will be ignored. If additional - * directories are specified GIO will load modules from the built-in - * directory last. - */ - - -/** - * SECTION:gaction - * @title: GAction - * @short_description: An action interface - * @include: gio/gio.h - * - * #GAction represents a single named action. - * - * The main interface to an action is that it can be activated with - * g_action_activate(). This results in the 'activate' signal being - * emitted. An activation has a #GVariant parameter (which may be - * %NULL). The correct type for the parameter is determined by a static - * parameter type (which is given at construction time). - * - * An action may optionally have a state, in which case the state may be - * set with g_action_change_state(). This call takes a #GVariant. The - * correct type for the state is determined by a static state type - * (which is given at construction time). - * - * The state may have a hint associated with it, specifying its valid - * range. - * - * #GAction is merely the interface to the concept of an action, as - * described above. Various implementations of actions exist, including - * #GSimpleAction. - * - * In all cases, the implementing class is responsible for storing the - * name of the action, the parameter type, the enabled state, the - * optional state type and the state and emitting the appropriate - * signals when these change. The implementor is responsible for filtering - * calls to g_action_activate() and g_action_change_state() for type - * safety and for the state being enabled. - * - * Probably the only useful thing to do with a #GAction is to put it - * inside of a #GSimpleActionGroup. - */ - - -/** - * SECTION:gactiongroup - * @title: GActionGroup - * @short_description: A group of actions - * @include: gio/gio.h - * @see_also: #GAction - * - * #GActionGroup represents a group of actions. Actions can be used to - * expose functionality in a structured way, either from one part of a - * program to another, or to the outside world. Action groups are often - * used together with a #GMenuModel that provides additional - * representation data for displaying the actions to the user, e.g. in - * a menu. - * - * The main way to interact with the actions in a GActionGroup is to - * activate them with g_action_group_activate_action(). Activating an - * action may require a #GVariant parameter. The required type of the - * parameter can be inquired with g_action_group_get_action_parameter_type(). - * Actions may be disabled, see g_action_group_get_action_enabled(). - * Activating a disabled action has no effect. - * - * Actions may optionally have a state in the form of a #GVariant. The - * current state of an action can be inquired with - * g_action_group_get_action_state(). Activating a stateful action may - * change its state, but it is also possible to set the state by calling - * g_action_group_change_action_state(). - * - * As typical example, consider a text editing application which has an - * option to change the current font to 'bold'. A good way to represent - * this would be a stateful action, with a boolean state. Activating the - * action would toggle the state. - * - * Each action in the group has a unique name (which is a string). All - * method calls, except g_action_group_list_actions() take the name of - * an action as an argument. - * - * The #GActionGroup API is meant to be the 'public' API to the action - * group. The calls here are exactly the interaction that 'external - * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have - * with actions. 'Internal' APIs (ie: ones meant only to be accessed by - * the action group implementation) are found on subclasses. This is - * why you will find - for example - g_action_group_get_action_enabled() - * but not an equivalent set() call. - * - * Signals are emitted on the action group in response to state changes - * on individual actions. - * - * Implementations of #GActionGroup should provide implementations for - * the virtual functions g_action_group_list_actions() and - * g_action_group_query_action(). The other virtual functions should - * not be implemented - their "wrappers" are actually implemented with - * calls to g_action_group_query_action(). - */ - - -/** - * SECTION:gactiongroupexporter - * @title: GActionGroup exporter - * @include: gio/gio.h - * @short_description: Export GActionGroups on D-Bus - * @see_also: #GActionGroup, #GDBusActionGroup - * - * These functions support exporting a #GActionGroup on D-Bus. - * The D-Bus interface that is used is a private implementation - * detail. - * - * To access an exported #GActionGroup remotely, use - * g_dbus_action_group_get() to obtain a #GDBusActionGroup. - */ - - -/** - * SECTION:gactionmap - * @title: GActionMap - * @include: gio/gio.h - * @short_description: Interface for action containers - * - * The GActionMap interface is implemented by #GActionGroup - * implementations that operate by containing a number of - * named #GAction instances, such as #GSimpleActionGroup. - * - * One useful application of this interface is to map the - * names of actions from various action groups to unique, - * prefixed names (e.g. by prepending "app." or "win."). - * This is the motivation for the 'Map' part of the interface - * name. - * - * Since: 2.32 - */ - - -/** - * SECTION:gappinfo - * @short_description: Application information and launch contexts - * @include: gio/gio.h - * @see_also: #GAppInfoMonitor - * - * #GAppInfo and #GAppLaunchContext are used for describing and launching - * applications installed on the system. - * - * As of GLib 2.20, URIs will always be converted to POSIX paths - * (using g_file_get_path()) when using g_app_info_launch() even if - * the application requested an URI and not a POSIX path. For example - * for a desktop-file based application with Exec key `totem - * %U` and a single URI, `sftp://foo/file.avi`, then - * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will - * only work if a set of suitable GIO extensions (such as gvfs 2.26 - * compiled with FUSE support), is available and operational; if this - * is not the case, the URI will be passed unmodified to the application. - * Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX - * path (in gvfs there's no FUSE mount for it); such URIs will be - * passed unmodified to the application. - * - * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped - * back to the GIO URI in the #GFile constructors (since gvfs - * implements the #GVfs extension point). As such, if the application - * needs to examine the URI, it needs to use g_file_get_uri() or - * similar on #GFile. In other words, an application cannot assume - * that the URI passed to e.g. g_file_new_for_commandline_arg() is - * equal to the result of g_file_get_uri(). The following snippet - * illustrates this: - * - * |[ - * GFile *f; - * char *uri; - * - * file = g_file_new_for_commandline_arg (uri_from_commandline); - * - * uri = g_file_get_uri (file); - * strcmp (uri, uri_from_commandline) == 0; - * g_free (uri); - * - * if (g_file_has_uri_scheme (file, "cdda")) - * { - * // do something special with uri - * } - * g_object_unref (file); - * ]| - * - * This code will work when both `cdda://sr0/Track 1.wav` and - * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the - * application. It should be noted that it's generally not safe - * for applications to rely on the format of a particular URIs. - * Different launcher applications (e.g. file managers) may have - * different ideas of what a given URI means. - */ - - -/** - * SECTION:gappinfomonitor - * @short_description: Monitor application information for changes - * - * #GAppInfoMonitor is a very simple object used for monitoring the app - * info database for changes (ie: newly installed or removed - * applications). - * - * Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect - * to the "changed" signal. - * - * In the usual case, applications should try to make note of the change - * (doing things like invalidating caches) but not act on it. In - * particular, applications should avoid making calls to #GAppInfo APIs - * in response to the change signal, deferring these until the time that - * the data is actually required. The exception to this case is when - * application information is actually being displayed on the screen - * (eg: during a search or when the list of all applications is shown). - * The reason for this is that changes to the list of installed - * applications often come in groups (like during system updates) and - * rescanning the list on every change is pointless and expensive. - * - * Since: 2.40 - */ - - -/** - * SECTION:gapplication - * @title: GApplication - * @short_description: Core application class - * @include: gio/gio.h - * - * A #GApplication is the foundation of an application. It wraps some - * low-level platform-specific services and is intended to act as the - * foundation for higher-level application classes such as - * #GtkApplication or #MxApplication. In general, you should not use - * this class outside of a higher level framework. - * - * GApplication provides convenient life cycle management by maintaining - * a "use count" for the primary application instance. The use count can - * be changed using g_application_hold() and g_application_release(). If - * it drops to zero, the application exits. Higher-level classes such as - * #GtkApplication employ the use count to ensure that the application - * stays alive as long as it has any opened windows. - * - * Another feature that GApplication (optionally) provides is process - * uniqueness. Applications can make use of this functionality by - * providing a unique application ID. If given, only one application - * with this ID can be running at a time per session. The session - * concept is platform-dependent, but corresponds roughly to a graphical - * desktop login. When your application is launched again, its - * arguments are passed through platform communication to the already - * running program. The already running instance of the program is - * called the "primary instance"; for non-unique applications this is - * always the current instance. On Linux, the D-Bus session bus - * is used for communication. - * - * The use of #GApplication differs from some other commonly-used - * uniqueness libraries (such as libunique) in important ways. The - * application is not expected to manually register itself and check - * if it is the primary instance. Instead, the main() function of a - * #GApplication should do very little more than instantiating the - * application instance, possibly connecting signal handlers, then - * calling g_application_run(). All checks for uniqueness are done - * internally. If the application is the primary instance then the - * startup signal is emitted and the mainloop runs. If the application - * is not the primary instance then a signal is sent to the primary - * instance and g_application_run() promptly returns. See the code - * examples below. - * - * If used, the expected form of an application identifier is the same as - * that of of a - * [D-Bus well-known bus name](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). - * Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`, - * `org._7_zip.Archiver`. - * For details on valid application identifiers, see g_application_id_is_valid(). - * - * On Linux, the application identifier is claimed as a well-known bus name - * on the user's session bus. This means that the uniqueness of your - * application is scoped to the current session. It also means that your - * application may provide additional services (through registration of other - * object paths) at that bus name. The registration of these object paths - * should be done with the shared GDBus session bus. Note that due to the - * internal architecture of GDBus, method calls can be dispatched at any time - * (even if a main loop is not running). For this reason, you must ensure that - * any object paths that you wish to register are registered before #GApplication - * attempts to acquire the bus name of your application (which happens in - * g_application_register()). Unfortunately, this means that you cannot use - * g_application_get_is_remote() to decide if you want to register object paths. - * - * GApplication also implements the #GActionGroup and #GActionMap - * interfaces and lets you easily export actions by adding them with - * g_action_map_add_action(). When invoking an action by calling - * g_action_group_activate_action() on the application, it is always - * invoked in the primary instance. The actions are also exported on - * the session bus, and GIO provides the #GDBusActionGroup wrapper to - * conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper - * for remote access to exported #GMenuModels. - * - * There is a number of different entry points into a GApplication: - * - * - via 'Activate' (i.e. just starting the application) - * - * - via 'Open' (i.e. opening some files) - * - * - by handling a command-line - * - * - via activating an action - * - * The #GApplication::startup signal lets you handle the application - * initialization for all of these in a single place. - * - * Regardless of which of these entry points is used to start the - * application, GApplication passes some ‘platform data’ from the - * launching instance to the primary instance, in the form of a - * #GVariant dictionary mapping strings to variants. To use platform - * data, override the @before_emit or @after_emit virtual functions - * in your #GApplication subclass. When dealing with - * #GApplicationCommandLine objects, the platform data is - * directly available via g_application_command_line_get_cwd(), - * g_application_command_line_get_environ() and - * g_application_command_line_get_platform_data(). - * - * As the name indicates, the platform data may vary depending on the - * operating system, but it always includes the current directory (key - * "cwd"), and optionally the environment (ie the set of environment - * variables and their values) of the calling process (key "environ"). - * The environment is only added to the platform data if the - * %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses - * can add their own platform data by overriding the @add_platform_data - * virtual function. For instance, #GtkApplication adds startup notification - * data in this way. - * - * To parse commandline arguments you may handle the - * #GApplication::command-line signal or override the local_command_line() - * vfunc, to parse them in either the primary instance or the local instance, - * respectively. - * - * For an example of opening files with a GApplication, see - * [gapplication-example-open.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-open.c). - * - * For an example of using actions with GApplication, see - * [gapplication-example-actions.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-actions.c). - * - * For an example of using extra D-Bus hooks with GApplication, see - * [gapplication-example-dbushooks.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c). - */ - - -/** - * SECTION:gapplicationcommandline - * @title: GApplicationCommandLine - * @short_description: A command-line invocation of an application - * @include: gio/gio.h - * @see_also: #GApplication - * - * #GApplicationCommandLine represents a command-line invocation of - * an application. It is created by #GApplication and emitted - * in the #GApplication::command-line signal and virtual function. - * - * The class contains the list of arguments that the program was invoked - * with. It is also possible to query if the commandline invocation was - * local (ie: the current process is running in direct response to the - * invocation) or remote (ie: some other process forwarded the - * commandline to this process). - * - * The GApplicationCommandLine object can provide the @argc and @argv - * parameters for use with the #GOptionContext command-line parsing API, - * with the g_application_command_line_get_arguments() function. See - * [gapplication-example-cmdline3.c][gapplication-example-cmdline3] - * for an example. - * - * The exit status of the originally-invoked process may be set and - * messages can be printed to stdout or stderr of that process. The - * lifecycle of the originally-invoked process is tied to the lifecycle - * of this object (ie: the process exits when the last reference is - * dropped). - * - * The main use for #GApplicationCommandLine (and the - * #GApplication::command-line signal) is 'Emacs server' like use cases: - * You can set the `EDITOR` environment variable to have e.g. git use - * your favourite editor to edit commit messages, and if you already - * have an instance of the editor running, the editing will happen - * in the running instance, instead of opening a new one. An important - * aspect of this use case is that the process that gets started by git - * does not return until the editing is done. - * - * Normally, the commandline is completely handled in the - * #GApplication::command-line handler. The launching instance exits - * once the signal handler in the primary instance has returned, and - * the return value of the signal handler becomes the exit status - * of the launching instance. - * |[ - * static int - * command_line (GApplication *application, - * GApplicationCommandLine *cmdline) - * { - * gchar **argv; - * gint argc; - * gint i; - * - * argv = g_application_command_line_get_arguments (cmdline, &argc); - * - * g_application_command_line_print (cmdline, - * "This text is written back\n" - * "to stdout of the caller\n"); - * - * for (i = 0; i < argc; i++) - * g_print ("argument %d: %s\n", i, argv[i]); - * - * g_strfreev (argv); - * - * return 0; - * } - * ]| - * The complete example can be found here: - * [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c) - * - * In more complicated cases, the handling of the comandline can be - * split between the launcher and the primary instance. - * |[ - * static gboolean - * test_local_cmdline (GApplication *application, - * gchar ***arguments, - * gint *exit_status) - * { - * gint i, j; - * gchar **argv; - * - * argv = *arguments; - * - * i = 1; - * while (argv[i]) - * { - * if (g_str_has_prefix (argv[i], "--local-")) - * { - * g_print ("handling argument %s locally\n", argv[i]); - * g_free (argv[i]); - * for (j = i; argv[j]; j++) - * argv[j] = argv[j + 1]; - * } - * else - * { - * g_print ("not handling argument %s locally\n", argv[i]); - * i++; - * } - * } - * - * *exit_status = 0; - * - * return FALSE; - * } - * - * static void - * test_application_class_init (TestApplicationClass *class) - * { - * G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline; - * - * ... - * } - * ]| - * In this example of split commandline handling, options that start - * with `--local-` are handled locally, all other options are passed - * to the #GApplication::command-line handler which runs in the primary - * instance. - * - * The complete example can be found here: - * [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c) - * - * If handling the commandline requires a lot of work, it may - * be better to defer it. - * |[ - * static gboolean - * my_cmdline_handler (gpointer data) - * { - * GApplicationCommandLine *cmdline = data; - * - * // do the heavy lifting in an idle - * - * g_application_command_line_set_exit_status (cmdline, 0); - * g_object_unref (cmdline); // this releases the application - * - * return G_SOURCE_REMOVE; - * } - * - * static int - * command_line (GApplication *application, - * GApplicationCommandLine *cmdline) - * { - * // keep the application running until we are done with this commandline - * g_application_hold (application); - * - * g_object_set_data_full (G_OBJECT (cmdline), - * "application", application, - * (GDestroyNotify)g_application_release); - * - * g_object_ref (cmdline); - * g_idle_add (my_cmdline_handler, cmdline); - * - * return 0; - * } - * ]| - * In this example the commandline is not completely handled before - * the #GApplication::command-line handler returns. Instead, we keep - * a reference to the #GApplicationCommandLine object and handle it - * later (in this example, in an idle). Note that it is necessary to - * hold the application until you are done with the commandline. - * - * The complete example can be found here: - * [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c) - */ - - -/** - * SECTION:gasyncinitable - * @short_description: Asynchronously failable object initialization interface - * @include: gio/gio.h - * @see_also: #GInitable - * - * This is the asynchronous version of #GInitable; it behaves the same - * in all ways except that initialization is asynchronous. For more details - * see the descriptions on #GInitable. - * - * A class may implement both the #GInitable and #GAsyncInitable interfaces. - * - * Users of objects implementing this are not intended to use the interface - * method directly; instead it will be used automatically in various ways. - * For C applications you generally just call g_async_initable_new_async() - * directly, or indirectly via a foo_thing_new_async() wrapper. This will call - * g_async_initable_init_async() under the cover, calling back with %NULL and - * a set %GError on failure. - * - * A typical implementation might look something like this: - * - * |[ - * enum { - * NOT_INITIALIZED, - * INITIALIZING, - * INITIALIZED - * }; - * - * static void - * _foo_ready_cb (Foo *self) - * { - * GList *l; - * - * self->priv->state = INITIALIZED; - * - * for (l = self->priv->init_results; l != NULL; l = l->next) - * { - * GTask *task = l->data; - * - * 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); - * self->priv->init_results = NULL; - * } - * - * static void - * foo_init_async (GAsyncInitable *initable, - * int io_priority, - * GCancellable *cancellable, - * GAsyncReadyCallback callback, - * gpointer user_data) - * { - * Foo *self = FOO (initable); - * GTask *task; - * - * task = g_task_new (initable, cancellable, callback, user_data); - * g_task_set_name (task, G_STRFUNC); - * - * switch (self->priv->state) - * { - * case NOT_INITIALIZED: - * _foo_get_ready (self); - * self->priv->init_results = g_list_append (self->priv->init_results, - * task); - * self->priv->state = INITIALIZING; - * break; - * case INITIALIZING: - * self->priv->init_results = g_list_append (self->priv->init_results, - * task); - * break; - * case INITIALIZED: - * if (!self->priv->success) - * g_task_return_new_error (task, ...); - * else - * g_task_return_boolean (task, TRUE); - * g_object_unref (task); - * break; - * } - * } - * - * static gboolean - * foo_init_finish (GAsyncInitable *initable, - * GAsyncResult *result, - * GError **error) - * { - * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE); - * - * return g_task_propagate_boolean (G_TASK (result), error); - * } - * - * static void - * foo_async_initable_iface_init (gpointer g_iface, - * gpointer data) - * { - * GAsyncInitableIface *iface = g_iface; - * - * iface->init_async = foo_init_async; - * iface->init_finish = foo_init_finish; - * } - * ]| - */ - - -/** - * SECTION:gasyncresult - * @short_description: Asynchronous Function Results - * @include: gio/gio.h - * @see_also: #GTask - * - * Provides a base class for implementing asynchronous function results. - * - * Asynchronous operations are broken up into two separate operations - * which are chained together by a #GAsyncReadyCallback. To begin - * an asynchronous operation, provide a #GAsyncReadyCallback to the - * asynchronous function. This callback will be triggered when the - * operation has completed, and must be run in a later iteration of - * the [thread-default main context][g-main-context-push-thread-default] - * from where the operation was initiated. It will be passed a - * #GAsyncResult instance filled with the details of the operation's - * success or failure, the object the asynchronous function was - * started for and any error codes returned. The asynchronous callback - * function is then expected to call the corresponding "_finish()" - * function, passing the object the function was called for, the - * #GAsyncResult instance, and (optionally) an @error to grab any - * error conditions that may have occurred. - * - * The "_finish()" function for an operation takes the generic result - * (of type #GAsyncResult) and returns the specific result that the - * operation in question yields (e.g. a #GFileEnumerator for a - * "enumerate children" operation). If the result or error status of the - * operation is not needed, there is no need to call the "_finish()" - * function; GIO will take care of cleaning up the result and error - * information after the #GAsyncReadyCallback returns. You can pass - * %NULL for the #GAsyncReadyCallback if you don't need to take any - * action at all after the operation completes. Applications may also - * take a reference to the #GAsyncResult and call "_finish()" later; - * however, the "_finish()" function may be called at most once. - * - * Example of a typical asynchronous operation flow: - * |[ - * void _theoretical_frobnitz_async (Theoretical *t, - * GCancellable *c, - * GAsyncReadyCallback cb, - * gpointer u); - * - * gboolean _theoretical_frobnitz_finish (Theoretical *t, - * GAsyncResult *res, - * GError **e); - * - * static void - * frobnitz_result_func (GObject *source_object, - * GAsyncResult *res, - * gpointer user_data) - * { - * gboolean success = FALSE; - * - * success = _theoretical_frobnitz_finish (source_object, res, NULL); - * - * if (success) - * g_printf ("Hurray!\n"); - * else - * g_printf ("Uh oh!\n"); - * - * ... - * - * } - * - * int main (int argc, void *argv[]) - * { - * ... - * - * _theoretical_frobnitz_async (theoretical_data, - * NULL, - * frobnitz_result_func, - * NULL); - * - * ... - * } - * ]| - * - * 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. - * - * ## I/O Priority # {#io-priority} - * - * 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 not 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. - */ - - -/** - * SECTION:gbufferedinputstream - * @short_description: Buffered Input Stream - * @include: gio/gio.h - * @see_also: #GFilterInputStream, #GInputStream - * - * Buffered input stream implements #GFilterInputStream and provides - * for buffered reads. - * - * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes. - * - * To create a buffered input stream, use g_buffered_input_stream_new(), - * or g_buffered_input_stream_new_sized() to specify the buffer's size at - * construction. - * - * To get the size of a buffer within a buffered input stream, use - * g_buffered_input_stream_get_buffer_size(). To change the size of a - * buffered input stream's buffer, use - * g_buffered_input_stream_set_buffer_size(). Note that the buffer's size - * cannot be reduced below the size of the data within the buffer. - */ - - -/** - * SECTION:gbufferedoutputstream - * @short_description: Buffered Output Stream - * @include: gio/gio.h - * @see_also: #GFilterOutputStream, #GOutputStream - * - * Buffered output stream implements #GFilterOutputStream and provides - * for buffered writes. - * - * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes. - * - * To create a buffered output stream, use g_buffered_output_stream_new(), - * or g_buffered_output_stream_new_sized() to specify the buffer's size - * at construction. - * - * To get the size of a buffer within a buffered input stream, use - * g_buffered_output_stream_get_buffer_size(). To change the size of a - * buffered output stream's buffer, use - * g_buffered_output_stream_set_buffer_size(). Note that the buffer's - * size cannot be reduced below the size of the data within the buffer. - */ - - -/** - * 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 - * - * GCancellable is a thread-safe operation cancellation stack used - * throughout GIO to allow for cancellation of synchronous and - * asynchronous operations. - */ - - -/** - * SECTION:gcharsetconverter - * @short_description: Convert between charsets - * @include: gio/gio.h - * - * #GCharsetConverter is an implementation of #GConverter based on - * GIConv. - */ - - -/** - * SECTION:gcontenttype - * @short_description: Platform-specific content typing - * @include: gio/gio.h - * - * A content type is a platform specific string that defines the type - * of a file. On UNIX it is a - * [MIME type](http://www.wikipedia.org/wiki/Internet_media_type) - * like `text/plain` or `image/png`. - * On Win32 it is an extension string like `.doc`, `.txt` or a perceived - * string like `audio`. Such strings can be looked up in the registry at - * `HKEY_CLASSES_ROOT`. - * On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier) - * such as `com.apple.application`. - */ - - -/** - * SECTION:gconverter - * @short_description: Data conversion interface - * @include: gio/gio.h - * @see_also: #GInputStream, #GOutputStream - * - * #GConverter is implemented by objects that convert - * binary data in various ways. The conversion can be - * stateful and may fail at any place. - * - * Some example conversions are: character set conversion, - * compression, decompression and regular expression - * replace. - * - * Since: 2.24 - */ - - -/** - * SECTION:gconverterinputstream - * @short_description: Converter Input Stream - * @include: gio/gio.h - * @see_also: #GInputStream, #GConverter - * - * Converter input stream implements #GInputStream and allows - * conversion of data of various types during reading. - * - * As of GLib 2.34, #GConverterInputStream implements - * #GPollableInputStream. - */ - - -/** - * SECTION:gconverteroutputstream - * @short_description: Converter Output Stream - * @include: gio/gio.h - * @see_also: #GOutputStream, #GConverter - * - * Converter output stream implements #GOutputStream and allows - * conversion of data of various types during reading. - * - * As of GLib 2.34, #GConverterOutputStream implements - * #GPollableOutputStream. - */ - - -/** - * SECTION:gcredentials - * @short_description: An object containing credentials - * @include: gio/gio.h - * - * The #GCredentials type is a reference-counted wrapper for native - * credentials. This information is typically used for identifying, - * authenticating and authorizing other processes. - * - * Some operating systems supports looking up the credentials of the - * remote peer of a communication endpoint - see e.g. - * g_socket_get_credentials(). - * - * Some operating systems supports securely sending and receiving - * credentials over a Unix Domain Socket, see - * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and - * g_unix_connection_receive_credentials() for details. - * - * On Linux, the native credential type is a `struct ucred` - see the - * unix(7) man page for details. This corresponds to - * %G_CREDENTIALS_TYPE_LINUX_UCRED. - * - * On Apple operating systems (including iOS, tvOS, and macOS), - * the native credential type is a `struct xucred`. - * This corresponds to %G_CREDENTIALS_TYPE_APPLE_XUCRED. - * - * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native - * credential type is a `struct cmsgcred`. This corresponds - * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. - * - * On NetBSD, the native credential type is a `struct unpcbid`. - * This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID. - * - * On OpenBSD, the native credential type is a `struct sockpeercred`. - * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED. - * - * On Solaris (including OpenSolaris and its derivatives), the native - * credential type is a `ucred_t`. This corresponds to - * %G_CREDENTIALS_TYPE_SOLARIS_UCRED. - */ - - -/** - * SECTION:gdatagrambased - * @short_description: Low-level datagram communications interface - * @include: gio/gio.h - * @see_also: #GSocket, [][gio-gnetworking.h] - * - * A #GDatagramBased is a networking interface for representing datagram-based - * communications. It is a more or less direct mapping of the core parts of the - * BSD socket API in a portable GObject interface. It is implemented by - * #GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows. - * - * #GDatagramBased is entirely platform independent, and is intended to be used - * alongside higher-level networking APIs such as #GIOStream. - * - * It uses vectored scatter/gather I/O by default, allowing for many messages - * to be sent or received in a single call. Where possible, implementations of - * the interface should take advantage of vectored I/O to minimise processing - * or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where - * possible. Callers should take advantage of scatter/gather I/O (the use of - * multiple buffers per message) to avoid unnecessary copying of data to - * assemble or disassemble a message. - * - * Each #GDatagramBased operation has a timeout parameter which may be negative - * for blocking behaviour, zero for non-blocking behaviour, or positive for - * timeout behaviour. A blocking operation blocks until finished or there is an - * error. A non-blocking operation will return immediately with a - * %G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation - * will block until the operation is complete or the timeout expires; if the - * timeout expires it will return what progress it made, or - * %G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would - * successfully run you can call g_datagram_based_condition_check() or - * g_datagram_based_condition_wait(). You can also use - * g_datagram_based_create_source() and attach it to a #GMainContext to get - * callbacks when I/O is possible. - * - * When running a non-blocking operation applications should always be able to - * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other function - * said that I/O was possible. This can easily happen in case of a race - * condition in the application, but it can also happen for other reasons. For - * instance, on Windows a socket is always seen as writable until a write - * returns %G_IO_ERROR_WOULD_BLOCK. - * - * As with #GSocket, #GDatagramBaseds can be either connection oriented (for - * example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be - * datagram-based, not stream-based. The interface does not cover connection - * establishment — use methods on the underlying type to establish a connection - * before sending and receiving data through the #GDatagramBased API. For - * connectionless socket types the target/source address is specified or - * received in each I/O operation. - * - * Like most other APIs in GLib, #GDatagramBased is not inherently thread safe. - * To use a #GDatagramBased concurrently from multiple threads, you must - * implement your own locking. - * - * Since: 2.48 - */ - - -/** - * SECTION:gdatainputstream - * @short_description: Data Input Stream - * @include: gio/gio.h - * @see_also: #GInputStream - * - * Data input stream implements #GInputStream and includes functions for - * reading structured data directly from a binary input stream. - */ - - -/** - * SECTION:gdataoutputstream - * @short_description: Data Output Stream - * @include: gio/gio.h - * @see_also: #GOutputStream - * - * Data output stream implements #GOutputStream and includes functions for - * writing data directly to an output stream. - */ - - -/** - * SECTION:gdbusactiongroup - * @title: GDBusActionGroup - * @short_description: A D-Bus GActionGroup implementation - * @include: gio/gio.h - * @see_also: [GActionGroup exporter][gio-GActionGroup-exporter] - * - * #GDBusActionGroup is an implementation of the #GActionGroup - * interface that can be used as a proxy for an action group - * that is exported over D-Bus with g_dbus_connection_export_action_group(). - */ - - -/** - * SECTION:gdbusaddress - * @title: D-Bus Addresses - * @short_description: D-Bus connection endpoints - * @include: gio/gio.h - * - * Routines for working with D-Bus addresses. A D-Bus address is a string - * like `unix:tmpdir=/tmp/my-app-name`. The exact format of addresses - * is explained in detail in the - * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - * - * TCP D-Bus connections are supported, but accessing them via a proxy is - * currently not supported. - */ - - -/** - * SECTION:gdbusauthobserver - * @short_description: Object used for authenticating connections - * @include: gio/gio.h - * - * The #GDBusAuthObserver type provides a mechanism for participating - * in how a #GDBusServer (or a #GDBusConnection) authenticates remote - * peers. Simply instantiate a #GDBusAuthObserver and connect to the - * signals you are interested in. Note that new signals may be added - * in the future - * - * ## Controlling Authentication Mechanisms - * - * By default, a #GDBusServer or server-side #GDBusConnection will allow - * any authentication mechanism to be used. If you only - * want to allow D-Bus connections with the `EXTERNAL` mechanism, - * which makes use of credentials passing and is the recommended - * mechanism for modern Unix platforms such as Linux and the BSD family, - * you would use a signal handler like this: - * - * |[ - * static gboolean - * on_allow_mechanism (GDBusAuthObserver *observer, - * const gchar *mechanism, - * gpointer user_data) - * { - * if (g_strcmp0 (mechanism, "EXTERNAL") == 0) - * { - * return TRUE; - * } - * - * return FALSE; - * } - * ]| - * - * ## Controlling Authorization # {#auth-observer} - * - * By default, a #GDBusServer or server-side #GDBusConnection will accept - * connections from any successfully authenticated user (but not from - * anonymous connections using the `ANONYMOUS` mechanism). If you only - * want to allow D-Bus connections from processes owned by the same uid - * as the server, since GLib 2.68, you should use the - * %G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag. It’s equivalent - * to the following signal handler: - * - * |[ - * static gboolean - * on_authorize_authenticated_peer (GDBusAuthObserver *observer, - * GIOStream *stream, - * GCredentials *credentials, - * gpointer user_data) - * { - * gboolean authorized; - * - * authorized = FALSE; - * if (credentials != NULL) - * { - * GCredentials *own_credentials; - * own_credentials = g_credentials_new (); - * if (g_credentials_is_same_user (credentials, own_credentials, NULL)) - * authorized = TRUE; - * g_object_unref (own_credentials); - * } - * - * return authorized; - * } - * ]| - */ - - -/** - * SECTION:gdbusconnection - * @short_description: D-Bus Connections - * @include: gio/gio.h - * - * The #GDBusConnection type is used for D-Bus connections to remote - * peers such as a message buses. It is a low-level API that offers a - * lot of flexibility. For instance, it lets you establish a connection - * over any transport that can by represented as a #GIOStream. - * - * This class is rarely used directly in D-Bus clients. If you are writing - * a D-Bus client, it is often easier to use the g_bus_own_name(), - * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs. - * - * As an exception to the usual GLib rule that a particular object must not - * be used by two threads at the same time, #GDBusConnection's methods may be - * called from any thread. This is so that g_bus_get() and g_bus_get_sync() - * can safely return the same #GDBusConnection when called from any thread. - * - * Most of the ways to obtain a #GDBusConnection automatically initialize it - * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and - * g_bus_get(), and the synchronous versions of those methods, give you an - * initialized connection. Language bindings for GIO should use - * g_initable_new() or g_async_initable_new_async(), which also initialize the - * connection. - * - * If you construct an uninitialized #GDBusConnection, such as via - * g_object_new(), you must initialize it via g_initable_init() or - * g_async_initable_init_async() before using its methods or properties. - * Calling methods or accessing properties on a #GDBusConnection that has not - * completed initialization successfully is considered to be invalid, and leads - * to undefined behaviour. In particular, if initialization fails with a - * #GError, the only valid thing you can do with that #GDBusConnection is to - * free it with g_object_unref(). - * - * ## An example D-Bus server # {#gdbus-server} - * - * Here is an example for a D-Bus server: - * [gdbus-example-server.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-server.c) - * - * ## An example for exporting a subtree # {#gdbus-subtree-server} - * - * Here is an example for exporting a subtree: - * [gdbus-example-subtree.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c) - * - * ## An example for file descriptor passing # {#gdbus-unix-fd-client} - * - * Here is an example for passing UNIX file descriptors: - * [gdbus-unix-fd-client.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c) - * - * ## An example for exporting a GObject # {#gdbus-export} - * - * Here is an example for exporting a #GObject: - * [gdbus-example-export.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c) - */ - - -/** - * SECTION:gdbuserror - * @title: GDBusError - * @short_description: Mapping D-Bus errors to and from GError - * @include: gio/gio.h - * - * All facilities that return errors from remote methods (such as - * g_dbus_connection_call_sync()) use #GError to represent both D-Bus - * errors (e.g. errors returned from the other peer) and locally - * in-process generated errors. - * - * To check if a returned #GError is an error from a remote peer, use - * g_dbus_error_is_remote_error(). To get the actual D-Bus error name, - * use g_dbus_error_get_remote_error(). Before presenting an error, - * always use g_dbus_error_strip_remote_error(). - * - * In addition, facilities used to return errors to a remote peer also - * use #GError. See g_dbus_method_invocation_return_error() for - * discussion about how the D-Bus error name is set. - * - * Applications can associate a #GError error domain with a set of D-Bus errors in order to - * automatically map from D-Bus errors to #GError and back. This - * is typically done in the function returning the #GQuark for the - * error domain: - * |[ - * // foo-bar-error.h: - * - * #define FOO_BAR_ERROR (foo_bar_error_quark ()) - * GQuark foo_bar_error_quark (void); - * - * typedef enum - * { - * FOO_BAR_ERROR_FAILED, - * FOO_BAR_ERROR_ANOTHER_ERROR, - * FOO_BAR_ERROR_SOME_THIRD_ERROR, - * FOO_BAR_N_ERRORS / *< skip >* / - * } FooBarError; - * - * // foo-bar-error.c: - * - * static const GDBusErrorEntry foo_bar_error_entries[] = - * { - * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"}, - * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"}, - * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"}, - * }; - * - * // Ensure that every error code has an associated D-Bus error name - * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS); - * - * GQuark - * foo_bar_error_quark (void) - * { - * static gsize quark = 0; - * g_dbus_error_register_error_domain ("foo-bar-error-quark", - * &quark, - * foo_bar_error_entries, - * G_N_ELEMENTS (foo_bar_error_entries)); - * return (GQuark) quark; - * } - * ]| - * 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 org.project.Foo.Bar.Error.AnotherError. - * - * 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 - * org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error(). - * - * Note that the %G_DBUS_ERROR error domain is intended only - * for returning errors from a remote message bus process. Errors - * generated locally in-process by e.g. #GDBusConnection should use the - * %G_IO_ERROR domain. - */ - - -/** - * SECTION:gdbusinterface - * @short_description: Base type for D-Bus interfaces - * @include: gio/gio.h - * - * The #GDBusInterface type is the base type for D-Bus interfaces both - * on the service side (see #GDBusInterfaceSkeleton) and client side - * (see #GDBusProxy). - */ - - -/** - * SECTION:gdbusinterfaceskeleton - * @short_description: Service-side D-Bus interface - * @include: gio/gio.h - * - * Abstract base class for D-Bus interfaces on the service side. - */ - - -/** - * SECTION:gdbusintrospection - * @title: D-Bus Introspection Data - * @short_description: Node and interface description data structures - * @include: gio/gio.h - * - * Various data structures and convenience routines to parse and - * generate D-Bus introspection XML. Introspection information is - * used when registering objects with g_dbus_connection_register_object(). - * - * The format of D-Bus introspection XML is specified in the - * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format) - */ - - -/** - * SECTION:gdbusmenumodel - * @title: GDBusMenuModel - * @short_description: A D-Bus GMenuModel implementation - * @include: gio/gio.h - * @see_also: [GMenuModel Exporter][gio-GMenuModel-exporter] - * - * #GDBusMenuModel is an implementation of #GMenuModel that can be used - * as a proxy for a menu model that is exported over D-Bus with - * g_dbus_connection_export_menu_model(). - */ - - -/** - * SECTION:gdbusmessage - * @short_description: D-Bus Message - * @include: gio/gio.h - * - * A type for representing D-Bus messages that can be sent or received - * on a #GDBusConnection. - */ - - -/** - * SECTION:gdbusmethodinvocation - * @short_description: Object for handling remote calls - * @include: gio/gio.h - * - * Instances of the #GDBusMethodInvocation class are used when - * handling D-Bus method calls. It provides a way to asynchronously - * return results and errors. - * - * The normal way to obtain a #GDBusMethodInvocation object is to receive - * it as an argument to the handle_method_call() function in a - * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object(). - */ - - -/** - * SECTION:gdbusnameowning - * @title: Owning Bus Names - * @short_description: Simple API for owning bus names - * @include: gio/gio.h - * - * Convenience API for owning bus names. - * - * A simple example for owning a name can be found in - * [gdbus-example-own-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-own-name.c) - */ - - -/** - * SECTION:gdbusnamewatching - * @title: Watching Bus Names - * @short_description: Simple API for watching bus names - * @include: gio/gio.h - * - * Convenience API for watching bus names. - * - * A simple example for watching a name can be found in - * [gdbus-example-watch-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-name.c) - */ - - -/** - * SECTION:gdbusobject - * @short_description: Base type for D-Bus objects - * @include: gio/gio.h - * - * The #GDBusObject type is the base type for D-Bus objects on both - * the service side (see #GDBusObjectSkeleton) and the client side - * (see #GDBusObjectProxy). It is essentially just a container of - * interfaces. - */ - - -/** - * SECTION:gdbusobjectmanager - * @short_description: Base type for D-Bus object managers - * @include: gio/gio.h - * - * The #GDBusObjectManager type is the base type for service- and - * client-side implementations of the standardized - * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) - * interface. - * - * See #GDBusObjectManagerClient for the client-side implementation - * and #GDBusObjectManagerServer for the service-side implementation. - */ - - -/** - * SECTION:gdbusobjectmanagerclient - * @short_description: Client-side object manager - * @include: gio/gio.h - * - * #GDBusObjectManagerClient is used to create, monitor and delete object - * proxies for remote objects exported by a #GDBusObjectManagerServer (or any - * code implementing the - * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) - * interface). - * - * Once an instance of this type has been created, you can connect to - * the #GDBusObjectManager::object-added and - * #GDBusObjectManager::object-removed signals and inspect the - * #GDBusObjectProxy objects returned by - * g_dbus_object_manager_get_objects(). - * - * If the name for a #GDBusObjectManagerClient is not owned by anyone at - * object construction time, the default behavior is to request the - * message bus to launch an owner for the name. This behavior can be - * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START - * flag. It's also worth noting that this only works if the name of - * interest is activatable in the first place. E.g. in some cases it - * is not possible to launch an owner for the requested name. In this - * case, #GDBusObjectManagerClient object construction still succeeds but - * there will be no object proxies - * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and - * the #GDBusObjectManagerClient:name-owner property is %NULL. - * - * The owner of the requested name can come and go (for example - * consider a system service being restarted) – #GDBusObjectManagerClient - * handles this case too; simply connect to the #GObject::notify - * signal to watch for changes on the #GDBusObjectManagerClient:name-owner - * property. When the name owner vanishes, the behavior is that - * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes - * emission of the #GObject::notify signal) and then - * #GDBusObjectManager::object-removed signals are synthesized - * for all currently existing object proxies. Since - * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can - * use this information to disambiguate a synthesized signal from a - * genuine signal caused by object removal on the remote - * #GDBusObjectManager. Similarly, when a new name owner appears, - * #GDBusObjectManager::object-added signals are synthesized - * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all - * object proxies have been added, the #GDBusObjectManagerClient:name-owner - * is set to the new name owner (this includes emission of the - * #GObject::notify signal). Furthermore, you are guaranteed that - * #GDBusObjectManagerClient:name-owner will alternate between a name owner - * (e.g. `:1.42`) and %NULL even in the case where - * the name of interest is atomically replaced - * - * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy - * instances. All signals (including the - * org.freedesktop.DBus.Properties::PropertiesChanged signal) - * delivered to #GDBusProxy instances are guaranteed to originate - * from the name owner. This guarantee along with the behavior - * described above, means that certain race conditions including the - * "half the proxy is from the old owner and the other half is from - * the new owner" problem cannot happen. - * - * To avoid having the application connect to signals on the returned - * #GDBusObjectProxy and #GDBusProxy objects, the - * #GDBusObject::interface-added, - * #GDBusObject::interface-removed, - * #GDBusProxy::g-properties-changed and - * #GDBusProxy::g-signal signals - * are also emitted on the #GDBusObjectManagerClient instance managing these - * objects. The signals emitted are - * #GDBusObjectManager::interface-added, - * #GDBusObjectManager::interface-removed, - * #GDBusObjectManagerClient::interface-proxy-properties-changed and - * #GDBusObjectManagerClient::interface-proxy-signal. - * - * Note that all callbacks and signals are emitted in the - * [thread-default main context][g-main-context-push-thread-default] - * that the #GDBusObjectManagerClient object was constructed - * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects - * originating from the #GDBusObjectManagerClient object will be created in - * the same context and, consequently, will deliver signals in the - * same main loop. - */ - - -/** - * SECTION:gdbusobjectmanagerserver - * @short_description: Service-side object manager - * @include: gio/gio.h - * - * #GDBusObjectManagerServer is used to export #GDBusObject instances using - * the standardized - * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) - * interface. For example, remote D-Bus clients can get all objects - * and properties in a single call. Additionally, any change in the - * object hierarchy is broadcast using signals. This means that D-Bus - * clients can keep caches up to date by only listening to D-Bus - * signals. - * - * The recommended path to export an object manager at is the path form of the - * well-known name of a D-Bus service, or below. For example, if a D-Bus service - * is available at the well-known name `net.example.ExampleService1`, the object - * manager should typically be exported at `/net/example/ExampleService1`, or - * below (to allow for multiple object managers in a service). - * - * It is supported, but not recommended, to export an object manager at the root - * path, `/`. - * - * See #GDBusObjectManagerClient for the client-side code that is - * intended to be used with #GDBusObjectManagerServer or any D-Bus - * object implementing the org.freedesktop.DBus.ObjectManager - * interface. - */ - - -/** - * SECTION:gdbusobjectproxy - * @short_description: Client-side D-Bus object - * @include: gio/gio.h - * - * A #GDBusObjectProxy is an object used to represent a remote object - * with one or more D-Bus interfaces. Normally, you don't instantiate - * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient - * is used to obtain it. - * - * Since: 2.30 - */ - - -/** - * SECTION:gdbusobjectskeleton - * @short_description: Service-side D-Bus object - * @include: gio/gio.h - * - * A #GDBusObjectSkeleton instance is essentially a group of D-Bus - * interfaces. The set of exported interfaces on the object may be - * dynamic and change at runtime. - * - * This type is intended to be used with #GDBusObjectManager. - */ - - -/** - * SECTION:gdbusproxy - * @short_description: Client-side D-Bus interface proxy - * @include: gio/gio.h - * - * #GDBusProxy is a base class used for proxies to access a D-Bus - * interface on a remote object. A #GDBusProxy can be constructed for - * both well-known and unique names. - * - * By default, #GDBusProxy will cache all properties (and listen to - * changes) of the remote object, and proxy all signals that get - * emitted. This behaviour can be changed by passing suitable - * #GDBusProxyFlags when the proxy is created. If the proxy is for a - * well-known name, the property cache is flushed when the name owner - * vanishes and reloaded when a name owner appears. - * - * The unique name owner of the proxy's name is tracked and can be read from - * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to - * get notified of changes. Additionally, only signals and property - * changes emitted from the current name owner are considered and - * calls are always sent to the current name owner. This avoids a - * number of race conditions when the name is lost by one owner and - * claimed by another. However, if no name owner currently exists, - * then calls will be sent to the well-known name which may result in - * the message bus launching an owner (unless - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). - * - * If the proxy is for a stateless D-Bus service, where the name owner may - * be started and stopped between calls, the #GDBusProxy:g-name-owner tracking - * of #GDBusProxy will cause the proxy to drop signal and property changes from - * the service after it has restarted for the first time. When interacting - * with a stateless D-Bus service, do not use #GDBusProxy — use direct D-Bus - * method calls and signal connections. - * - * The generic #GDBusProxy::g-properties-changed and - * #GDBusProxy::g-signal signals are not very convenient to work with. - * Therefore, the recommended way of working with proxies is to subclass - * #GDBusProxy, and have more natural properties and signals in your derived - * class. This [example][gdbus-example-gdbus-codegen] shows how this can - * easily be done using the [gdbus-codegen][gdbus-codegen] tool. - * - * A #GDBusProxy instance can be used from multiple threads but note - * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed - * and #GObject::notify) are emitted in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread where the instance was constructed. - * - * An example using a proxy for a well-known name can be found in - * [gdbus-example-watch-proxy.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c) - */ - - -/** - * SECTION:gdbusserver - * @short_description: Helper for accepting connections - * @include: gio/gio.h - * - * #GDBusServer is a helper for listening to and accepting D-Bus - * connections. This can be used to create a new D-Bus server, allowing two - * peers to use the D-Bus protocol for their own specialized communication. - * A server instance provided in this way will not perform message routing or - * implement the org.freedesktop.DBus interface. - * - * To just export an object on a well-known name on a message bus, such as the - * session or system bus, you should instead use g_bus_own_name(). - * - * An example of peer-to-peer communication with GDBus can be found - * in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c). - * - * Note that a minimal #GDBusServer will accept connections from any - * peer. In many use-cases it will be necessary to add a #GDBusAuthObserver - * that only accepts connections that have successfully authenticated - * as the same user that is running the #GDBusServer. Since GLib 2.68 this can - * be achieved more simply by passing the - * %G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag to the server. - */ - - -/** - * SECTION:gdbusutils - * @title: D-Bus Utilities - * @short_description: Various utilities related to D-Bus - * @include: gio/gio.h - * - * Various utility routines related to D-Bus. - */ - - -/** - * SECTION:gdesktopappinfo - * @title: GDesktopAppInfo - * @short_description: Application information from desktop files - * @include: gio/gdesktopappinfo.h - * - * #GDesktopAppInfo is an implementation of #GAppInfo based on - * desktop files. - * - * Note that `` belongs to the UNIX-specific - * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config - * file when using it. - */ - - -/** - * SECTION:gdrive - * @short_description: Drive management - * @include: gio/gio.h - * - * #GDrive - this represent a piece of hardware connected to the machine. - * It's generally only created for removable hardware or hardware with - * removable media. - * - * #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, determining whether media change is - * automatically detected and ejecting the media. - * - * If the #GDrive reports that media isn't automatically detected, one - * can poll for media; typically one should not do this periodically - * as a poll for media operation is potentially expensive and may - * spin up the drive creating noise. - * - * #GDrive supports starting and stopping drives with authentication - * support for the former. This can be used to support a diverse set - * of use cases including connecting/disconnecting iSCSI devices, - * powering down external disk enclosures and starting/stopping - * multi-disk devices such as RAID devices. Note that the actual - * semantics and side-effects of starting/stopping a #GDrive may vary - * according to implementation. To choose the correct verbs in e.g. a - * file manager, use g_drive_get_start_stop_type(). - * - * For porting from GnomeVFS note that there is no equivalent of - * #GDrive in that API. - */ - - -/** - * SECTION:gdtlsclientconnection - * @short_description: DTLS client-side connection - * @include: gio/gio.h - * - * #GDtlsClientConnection is the client-side subclass of - * #GDtlsConnection, representing a client-side DTLS connection. - * - * Since: 2.48 - */ - - -/** - * SECTION:gdtlsconnection - * @short_description: DTLS connection type - * @include: gio/gio.h - * - * #GDtlsConnection is the base DTLS connection class type, which wraps - * a #GDatagramBased and provides DTLS encryption on top of it. Its - * subclasses, #GDtlsClientConnection and #GDtlsServerConnection, - * implement client-side and server-side DTLS, respectively. - * - * For TLS support, see #GTlsConnection. - * - * As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased, - * presenting a datagram-socket-like API for the encrypted connection. This - * operates over a base datagram connection, which is also a #GDatagramBased - * (#GDtlsConnection:base-socket). - * - * To close a DTLS connection, use g_dtls_connection_close(). - * - * Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address - * on their base #GDatagramBased if it is a #GSocket — it is up to the caller to - * do that if they wish. If they do not, and g_socket_close() is called on the - * base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED - * error on further I/O. - * - * Since: 2.48 - */ - - -/** - * SECTION:gdtlsserverconnection - * @short_description: DTLS server-side connection - * @include: gio/gio.h - * - * #GDtlsServerConnection is the server-side subclass of #GDtlsConnection, - * representing a server-side DTLS connection. - * - * Since: 2.48 - */ - - -/** - * SECTION:gemblem - * @short_description: An object for emblems - * @include: gio/gio.h - * @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon - * - * #GEmblem is an implementation of #GIcon that supports - * having an emblem, which is an icon with additional properties. - * It can than be added to a #GEmblemedIcon. - * - * Currently, only metainformation about the emblem's origin is - * supported. More may be added in the future. - */ - - -/** - * SECTION:gemblemedicon - * @short_description: Icon with emblems - * @include: gio/gio.h - * @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem - * - * #GEmblemedIcon is an implementation of #GIcon that supports - * adding an emblem to an icon. Adding multiple emblems to an - * icon is ensured via g_emblemed_icon_add_emblem(). - * - * Note that #GEmblemedIcon allows no control over the position - * of the emblems. See also #GEmblem for more information. - */ - - -/** - * SECTION:gfile - * @short_description: File and Directory Handling - * @include: gio/gio.h - * @see_also: #GFileInfo, #GFileEnumerator - * - * #GFile is a high level abstraction for manipulating files on a - * virtual file system. #GFiles are lightweight, immutable objects - * that do no I/O upon creation. It is necessary to understand that - * #GFile objects do not represent files, merely an identifier for a - * file. All file content I/O is implemented as streaming operations - * (see #GInputStream and #GOutputStream). - * - * To construct a #GFile, you can use: - * - g_file_new_for_path() if you have a path. - * - g_file_new_for_uri() if you have a URI. - * - g_file_new_for_commandline_arg() for a command line argument. - * - g_file_new_tmp() to create a temporary file from a template. - * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). - * - g_file_new_build_filename() to create a file from path elements. - * - * One way to think of a #GFile is as an abstraction of a pathname. For - * normal files the system pathname is what is stored internally, but as - * #GFiles are extensible it could also be something else that corresponds - * to a pathname in a userspace implementation of a filesystem. - * - * #GFiles make up hierarchies of directories and files that correspond to - * the files on a filesystem. You can move through the file system with - * #GFile using g_file_get_parent() to get an identifier for the parent - * directory, g_file_get_child() to get a child within a directory, - * g_file_resolve_relative_path() to resolve a relative path between two - * #GFiles. There can be multiple hierarchies, so you may not end up at - * the same root if you repeatedly call g_file_get_parent() on two different - * files. - * - * All #GFiles have a basename (get with g_file_get_basename()). These names - * are byte strings that are used to identify the file on the filesystem - * (relative to its parent directory) and there is no guarantees that they - * have any particular charset encoding or even make any sense at all. If - * you want to use filenames in a user interface you should use the display - * name that you can get by requesting the - * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). - * This is guaranteed to be in UTF-8 and can be used in a user interface. - * But always store the real basename or the #GFile to use to actually - * access the file, because there is no way to go from a display name to - * the actual name. - * - * Using #GFile as an identifier has the same weaknesses as using a path - * in that there may be multiple aliases for the same file. For instance, - * hard or soft links may cause two different #GFiles to refer to the same - * file. Other possible causes for aliases are: case insensitive filesystems, - * short and long names on FAT/NTFS, or bind mounts in Linux. If you want to - * check if two #GFiles point to the same file you can query for the - * %G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial - * canonicalization of pathnames passed in, so that trivial differences in - * the path string used at creation (duplicated slashes, slash at end of - * path, "." or ".." path segments, etc) does not create different #GFiles. - * - * Many #GFile operations have both synchronous and asynchronous versions - * to suit your application. Asynchronous versions of synchronous functions - * simply have _async() appended to their function names. The asynchronous - * I/O functions call a #GAsyncReadyCallback which is then used to finalize - * the operation, producing a GAsyncResult which is then passed to the - * function's matching _finish() operation. - * - * It is highly recommended to use asynchronous calls when running within a - * shared main loop, such as in the main thread of an application. This avoids - * I/O operations blocking other sources on the main loop from being dispatched. - * Synchronous I/O operations should be performed from worker threads. See the - * [introduction to asynchronous programming section][async-programming] for - * more. - * - * Some #GFile operations almost always take a noticeable amount of time, and - * so do not have synchronous analogs. Notable cases include: - * - g_file_mount_mountable() to mount a mountable file. - * - g_file_unmount_mountable_with_operation() to unmount a mountable file. - * - g_file_eject_mountable_with_operation() to eject a mountable file. - * - * ## Entity Tags # {#gfile-etag} - * - * One notable feature of #GFiles are entity tags, or "etags" for - * short. Entity tags are somewhat like a more abstract version of the - * traditional mtime, and can be used to quickly determine if the file - * has been modified from the version on the file system. See the - * HTTP 1.1 - * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) - * for HTTP Etag headers, which are a very similar concept. - */ - - -/** - * SECTION:gfileattribute - * @short_description: Key-Value Paired File Attributes - * @include: gio/gio.h - * @see_also: #GFile, #GFileInfo - * - * 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 - * key-value pairs by namespaces for relevance. Keys can be retrieved - * using wildcards, e.g. "standard::*" will return all of the keys in the - * "standard" namespace. - * - * The list of possible attributes for a filesystem (pointed to by a #GFile) is - * available as a #GFileAttributeInfoList. This list is queryable by key names - * as indicated earlier. - * - * Information is stored within the list in #GFileAttributeInfo structures. - * The info structure can store different types, listed in the enum - * #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will - * be set to %G_FILE_ATTRIBUTE_TYPE_INVALID. - * - * Classes that implement #GFileIface will create a #GFileAttributeInfoList and - * install default keys and values for their given file system, architecture, - * and other possible implementation details (e.g., on a UNIX system, a file - * attribute key will be registered for the user id for a given file). - * - * ## Default Namespaces - * - * - `"standard"`: The "Standard" namespace. General file information that - * any application may need should be put in this namespace. Examples - * include the file's name, type, and size. - * - `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key - * in this namespace is "value", which contains the value of the current - * entity tag. - * - `"id"`: The "Identification" namespace. This namespace is used by file - * managers and applications that list directories to check for loops and - * to uniquely identify files. - * - `"access"`: The "Access" namespace. Used to check if a user has the - * proper privileges to access files and perform file operations. Keys in - * this namespace are made to be generic and easily understood, e.g. the - * "can_read" key is %TRUE if the current user has permission to read the - * file. UNIX permissions and NTFS ACLs in Windows should be mapped to - * these values. - * - `"mountable"`: The "Mountable" namespace. Includes simple boolean keys - * for checking if a file or path supports mount operations, e.g. mount, - * unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE. - * - `"time"`: The "Time" namespace. Includes file access, changed, created - * times. - * - `"unix"`: The "Unix" namespace. Includes UNIX-specific information and - * may not be available for all files. Examples include the UNIX "UID", - * "GID", etc. - * - `"dos"`: The "DOS" namespace. Includes DOS-specific information and may - * not be available for all files. Examples include "is_system" for checking - * if a file is marked as a system file, and "is_archive" for checking if a - * file is marked as an archive file. - * - `"owner"`: The "Owner" namespace. Includes information about who owns a - * file. May not be available for all file systems. Examples include "user" - * for getting the user name of the file owner. This information is often - * mapped from some backend specific data such as a UNIX UID. - * - `"thumbnail"`: The "Thumbnail" namespace. Includes information about file - * thumbnails and their location within the file system. Examples of keys in - * this namespace include "path" to get the location of a thumbnail, "failed" - * to check if thumbnailing of the file failed, and "is-valid" to check if - * the thumbnail is outdated. - * - `"filesystem"`: The "Filesystem" namespace. Gets information about the - * file system where a file is located, such as its type, how much space is - * left available, and the overall size of the file system. - * - `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information - * about the current GVFS backend in use. - * - `"xattr"`: The "xattr" namespace. Gets information about extended - * user attributes. See attr(5). The "user." prefix of the extended user - * attribute name is stripped away when constructing keys in this namespace, - * e.g. "xattr::mime_type" for the extended attribute with the name - * "user.mime_type". Note that this information is only available if - * GLib has been built with extended attribute support. - * - `"xattr-sys"`: The "xattr-sys" namespace. Gets information about - * extended attributes which are not user-specific. See attr(5). Note - * that this information is only available if GLib has been built with - * extended attribute support. - * - `"selinux"`: The "SELinux" namespace. Includes information about the - * SELinux context of files. Note that this information is only available - * if GLib has been built with SELinux support. - * - * Please note that these are not all of the possible namespaces. - * More namespaces can be added from GIO modules or by individual applications. - * For more information about writing GIO modules, see #GIOModule. - * - * - * - * ## Default Keys - * - * For a list of the built-in keys and their types, see the - * [GFileInfo][GFileInfo] documentation. - * - * Note that there are no predefined keys in the "xattr" and "xattr-sys" - * namespaces. Keys for the "xattr" namespace are constructed by stripping - * away the "user." prefix from the extended user attribute, and prepending - * "xattr::". Keys for the "xattr-sys" namespace are constructed by - * concatenating "xattr-sys::" with the extended attribute name. All extended - * attribute values are returned as hex-encoded strings in which bytes outside - * the ASCII range are encoded as escape sequences of the form \x`nn` - * where `nn` is a 2-digit hexadecimal number. - */ - - -/** - * SECTION:gfiledescriptorbased - * @short_description: Interface for file descriptor based IO - * @include: gio/gfiledescriptorbased.h - * @see_also: #GInputStream, #GOutputStream - * - * #GFileDescriptorBased is implemented by streams (implementations of - * #GInputStream or #GOutputStream) that are based on file descriptors. - * - * Note that `` belongs to the UNIX-specific - * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config - * file when using it. - * - * Since: 2.24 - */ - - -/** - * SECTION:gfileenumerator - * @short_description: Enumerated Files Routines - * @include: gio/gio.h - * - * #GFileEnumerator allows you to operate on a set of #GFiles, - * returning a #GFileInfo structure for each file enumerated (e.g. - * g_file_enumerate_children() will return a #GFileEnumerator for each - * of the children within a directory). - * - * To get the next file's information from a #GFileEnumerator, use - * g_file_enumerator_next_file() or its asynchronous version, - * g_file_enumerator_next_files_async(). Note that the asynchronous - * version will return a list of #GFileInfos, 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 - * on it, and it should be freed with g_object_unref(). - */ - - -/** - * SECTION:gfileicon - * @short_description: Icons pointing to an image file - * @include: gio/gio.h - * @see_also: #GIcon, #GLoadableIcon - * - * #GFileIcon specifies an icon by pointing to an image file - * to be used as icon. - */ - - -/** - * SECTION:gfileinfo - * @short_description: File Information and Attributes - * @include: gio/gio.h - * @see_also: #GFile, [GFileAttribute][gio-GFileAttribute] - * - * Functionality for manipulating basic metadata for files. #GFileInfo - * implements methods for getting information that all files should - * contain, and allows for manipulation of extended attributes. - * - * See [GFileAttribute][gio-GFileAttribute] for more information on how - * GIO handles file attributes. - * - * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its - * async variant). To obtain a #GFileInfo for a file input or output - * stream, use g_file_input_stream_query_info() or - * g_file_output_stream_query_info() (or their async variants). - * - * To change the actual attributes of a file, you should then set the - * attribute in the #GFileInfo and call g_file_set_attributes_from_info() - * or g_file_set_attributes_async() on a GFile. - * - * However, not all attributes can be changed in the file. For instance, - * the actual size of a file cannot be changed via g_file_info_set_size(). - * You may call g_file_query_settable_attributes() and - * g_file_query_writable_namespaces() to discover the settable attributes - * of a particular file at runtime. - * - * The direct accessors, such as g_file_info_get_name(), are slightly more - * optimized than the generic attribute accessors, such as - * g_file_info_get_attribute_byte_string().This optimization will matter - * only if calling the API in a tight loop. - * - * #GFileAttributeMatcher allows for searching through a #GFileInfo for - * attributes. - */ - - -/** - * SECTION:gfileinputstream - * @short_description: File input streaming operations - * @include: gio/gio.h - * @see_also: #GInputStream, #GDataInputStream, #GSeekable - * - * GFileInputStream provides input streams that take their - * content from a file. - * - * GFileInputStream implements #GSeekable, which allows the input - * stream to jump to arbitrary positions in the file, provided the - * filesystem of the file allows it. To find the position of a file - * input stream, use g_seekable_tell(). To find out if a file input - * stream supports seeking, use g_seekable_can_seek(). - * To position a file input stream, use g_seekable_seek(). - */ - - -/** - * SECTION:gfileiostream - * @short_description: File read and write streaming operations - * @include: gio/gio.h - * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable - * - * GFileIOStream provides io streams that both read and write to the same - * file handle. - * - * GFileIOStream implements #GSeekable, which allows the io - * stream to jump to arbitrary positions in the file and to truncate - * the file, provided the filesystem of the file supports these - * operations. - * - * To find the position of a file io stream, use - * g_seekable_tell(). - * - * To find out if a file io stream supports seeking, use g_seekable_can_seek(). - * To position a file io stream, use g_seekable_seek(). - * To find out if a file io stream supports truncating, use - * g_seekable_can_truncate(). To truncate a file io - * stream, use g_seekable_truncate(). - * - * The default implementation of all the #GFileIOStream operations - * and the implementation of #GSeekable just call into the same operations - * on the output stream. - * - * Since: 2.22 - */ - - -/** - * SECTION:gfilemonitor - * @short_description: File Monitor - * @include: gio/gio.h - * - * Monitors a file or directory for changes. - * - * To obtain a #GFileMonitor for a file or directory, use - * g_file_monitor(), g_file_monitor_file(), or - * g_file_monitor_directory(). - * - * To get informed about changes to the file or directory you are - * monitoring, connect to the #GFileMonitor::changed signal. The - * signal will be emitted in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread that the monitor was created in - * (though if the global default main context is blocked, this may - * cause notifications to be blocked even if the thread-default - * context is still running). - */ - - -/** - * SECTION:gfilenamecompleter - * @short_description: Filename Completer - * @include: gio/gio.h - * - * Completes partial file and directory names given a partial string by - * looking in the file system for clues. Can return a list of possible - * completion strings for widget implementations. - */ - - -/** - * SECTION:gfileoutputstream - * @short_description: File output streaming operations - * @include: gio/gio.h - * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable - * - * GFileOutputStream provides output streams that write their - * content to a file. - * - * GFileOutputStream implements #GSeekable, which allows the output - * stream to jump to arbitrary positions in the file and to truncate - * the file, provided the filesystem of the file supports these - * operations. - * - * To find the position of a file output stream, use g_seekable_tell(). - * To find out if a file output stream supports seeking, use - * g_seekable_can_seek().To position a file output stream, use - * g_seekable_seek(). To find out if a file output stream supports - * truncating, use g_seekable_can_truncate(). To truncate a file output - * stream, use g_seekable_truncate(). - */ - - -/** - * SECTION:gfilterinputstream - * @short_description: Filter Input Stream - * @include: gio/gio.h - * - * Base class for input stream implementations that perform some - * kind of filtering operation on a base stream. Typical examples - * of filtering operations are character set conversion, compression - * and byte order flipping. - */ - - -/** - * SECTION:gfilteroutputstream - * @short_description: Filter Output Stream - * @include: gio/gio.h - * - * Base class for output stream implementations that perform some - * kind of filtering operation on a base stream. Typical examples - * of filtering operations are character set conversion, compression - * and byte order flipping. - */ - - -/** - * SECTION:gicon - * @short_description: Interface for icons - * @include: gio/gio.h - * - * #GIcon is a very minimal interface for icons. It provides functions - * for checking the equality of two icons, hashing of icons and - * serializing an icon to and from strings. - * - * #GIcon does not provide the actual pixmap for the icon as this is out - * of GIO's scope, however implementations of #GIcon may contain the name - * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon). - * - * To obtain a hash of a #GIcon, see g_icon_hash(). - * - * To check if two #GIcons are equal, see g_icon_equal(). - * - * 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 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. - */ - - -/** - * SECTION:ginetaddress - * @short_description: An IPv4/IPv6 address - * @include: gio/gio.h - * - * #GInetAddress represents an IPv4 or IPv6 internet address. Use - * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to - * look up the #GInetAddress for a hostname. Use - * g_resolver_lookup_by_address() or - * g_resolver_lookup_by_address_async() to look up the hostname for a - * #GInetAddress. - * - * To actually connect to a remote host, you will need a - * #GInetSocketAddress (which includes a #GInetAddress as well as a - * port number). - */ - - -/** - * SECTION:ginetaddressmask - * @short_description: An IPv4/IPv6 address mask - * @include: gio/gio.h - * - * #GInetAddressMask represents a range of IPv4 or IPv6 addresses - * described by a base address and a length indicating how many bits - * of the base address are relevant for matching purposes. These are - * often given in string form. Eg, "10.0.0.0/8", or "fe80::/10". - */ - - -/** - * SECTION:ginetsocketaddress - * @short_description: Internet GSocketAddress - * @include: gio/gio.h - * - * An IPv4 or IPv6 socket address; that is, the combination of a - * #GInetAddress and a port number. - */ - - -/** - * SECTION:ginitable - * @short_description: Failable object initialization interface - * @include: gio/gio.h - * @see_also: #GAsyncInitable - * - * #GInitable is implemented by objects that can fail during - * initialization. If an object implements this interface then - * it must be initialized as the first thing after construction, - * either via g_initable_init() or g_async_initable_init_async() - * (the latter is only available if it also implements #GAsyncInitable). - * - * If the object is not initialized, or initialization returns with an - * error, then all operations on the object except g_object_ref() and - * g_object_unref() are considered to be invalid, and have undefined - * behaviour. They will often fail with g_critical() or g_warning(), but - * this must not be relied on. - * - * Users of objects implementing this are not intended to use - * the interface method directly, instead it will be used automatically - * in various ways. For C applications you generally just call - * g_initable_new() directly, or indirectly via a foo_thing_new() wrapper. - * This will call g_initable_init() under the cover, returning %NULL and - * setting a #GError on failure (at which point the instance is - * unreferenced). - * - * For bindings in languages where the native constructor supports - * exceptions the binding could check for objects implementing %GInitable - * during normal construction and automatically initialize them, throwing - * an exception on failure. - */ - - -/** - * SECTION:ginputstream - * @short_description: Base class for implementing streaming input - * @include: gio/gio.h - * - * #GInputStream has functions to read from a stream (g_input_stream_read()), - * to close a stream (g_input_stream_close()) and to skip some content - * (g_input_stream_skip()). - * - * To copy the content of an input stream to an output stream without - * manually handling the reads and writes, use g_output_stream_splice(). - * - * See the documentation for #GIOStream for details of thread safety of - * streaming APIs. - * - * All of these functions have async variants too. - */ - - -/** - * SECTION:gioerror - * @short_description: Error helper functions - * @include: gio/gio.h - * - * Contains helper functions for reporting errors to the user. - */ - - -/** - * SECTION:giomodule - * @short_description: Loadable GIO Modules - * @include: gio/gio.h - * - * Provides an interface and default functions for loading and unloading - * modules. This is used internally to make GIO extensible, but can also - * be used by others to implement module loading. - */ - - -/** - * SECTION:gioscheduler - * @short_description: I/O Scheduler - * @include: gio/gio.h - * - * As of GLib 2.36, #GIOScheduler is deprecated in favor of - * #GThreadPool and #GTask. - * - * Schedules asynchronous I/O operations. #GIOScheduler integrates - * into the main event loop (#GMainLoop) and uses threads. - */ - - -/** - * SECTION:giostream - * @short_description: Base class for implementing read/write streams - * @include: gio/gio.h - * @see_also: #GInputStream, #GOutputStream - * - * GIOStream represents an object that has both read and write streams. - * Generally the two streams act as separate input and output streams, - * but they share some common resources and state. For instance, for - * seekable streams, both streams may use the same position. - * - * Examples of #GIOStream objects are #GSocketConnection, which represents - * a two-way network connection; and #GFileIOStream, which represents a - * file handle opened in read-write mode. - * - * To do the actual reading and writing you need to get the substreams - * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream(). - * - * The #GIOStream object owns the input and the output streams, not the other - * way around, so keeping the substreams alive will not keep the #GIOStream - * object alive. If the #GIOStream object is freed it will be closed, thus - * closing the substreams, so even if the substreams stay alive they will - * always return %G_IO_ERROR_CLOSED for all operations. - * - * To close a stream use g_io_stream_close() which will close the common - * stream object and also the individual substreams. You can also close - * the substreams themselves. In most cases this only marks the - * substream as closed, so further I/O on it fails but common state in the - * #GIOStream may still be open. However, some streams may support - * "half-closed" states where one direction of the stream is actually shut down. - * - * Operations on #GIOStreams cannot be started while another operation on the - * #GIOStream or its substreams is in progress. Specifically, an application can - * read from the #GInputStream and write to the #GOutputStream simultaneously - * (either in separate threads, or as asynchronous operations in the same - * thread), but an application cannot start any #GIOStream operation while there - * is a #GIOStream, #GInputStream or #GOutputStream operation in progress, and - * an application can’t start any #GInputStream or #GOutputStream operation - * while there is a #GIOStream operation in progress. - * - * This is a product of individual stream operations being associated with a - * given #GMainContext (the thread-default context at the time the operation was - * started), rather than entire streams being associated with a single - * #GMainContext. - * - * GIO may run operations on #GIOStreams from other (worker) threads, and this - * may be exposed to application code in the behaviour of wrapper streams, such - * as #GBufferedInputStream or #GTlsConnection. With such wrapper APIs, - * application code may only run operations on the base (wrapped) stream when - * the wrapper stream is idle. Note that the semantics of such operations may - * not be well-defined due to the state the wrapper stream leaves the base - * stream in (though they are guaranteed not to crash). - * - * Since: 2.22 - */ - - -/** - * SECTION:glistmodel - * @title: GListModel - * @short_description: An interface describing a dynamic list of objects - * @include: gio/gio.h - * @see_also: #GListStore - * - * #GListModel is an interface that represents a mutable list of - * #GObjects. Its main intention is as a model for various widgets in - * user interfaces, such as list views, but it can also be used as a - * convenient method of returning lists of data, with support for - * updates. - * - * Each object in the list may also report changes in itself via some - * mechanism (normally the #GObject::notify signal). Taken together - * with the #GListModel::items-changed signal, this provides for a list - * that can change its membership, and in which the members can change - * their individual properties. - * - * A good example would be the list of visible wireless network access - * points, where each access point can report dynamic properties such as - * signal strength. - * - * It is important to note that the #GListModel itself does not report - * changes to the individual items. It only reports changes to the list - * membership. If you want to observe changes to the objects themselves - * then you need to connect signals to the objects that you are - * interested in. - * - * All items in a #GListModel are of (or derived from) the same type. - * g_list_model_get_item_type() returns that type. The type may be an - * interface, in which case all objects in the list must implement it. - * - * The semantics are close to that of an array: - * g_list_model_get_n_items() returns the number of items in the list and - * g_list_model_get_item() returns an item at a (0-based) position. In - * order to allow implementations to calculate the list length lazily, - * you can also iterate over items: starting from 0, repeatedly call - * g_list_model_get_item() until it returns %NULL. - * - * An implementation may create objects lazily, but must take care to - * return the same object for a given position until all references to - * it are gone. - * - * On the other side, a consumer is expected only to hold references on - * objects that are currently "user visible", in order to facilitate the - * maximum level of laziness in the implementation of the list and to - * reduce the required number of signal connections at a given time. - * - * This interface is intended only to be used from a single thread. The - * thread in which it is appropriate to use it depends on the particular - * implementation, but typically it will be from the thread that owns - * the [thread-default main context][g-main-context-push-thread-default] - * in effect at the time that the model was created. - */ - - -/** - * SECTION:gliststore - * @title: GListStore - * @short_description: A simple implementation of #GListModel - * @include: gio/gio.h - * - * #GListStore is a simple implementation of #GListModel that stores all - * items in memory. - * - * It provides insertions, deletions, and lookups in logarithmic time - * with a fast path for the common case of iterating the list linearly. - */ - - -/** - * SECTION:gloadableicon - * @short_description: Loadable Icons - * @include: gio/gio.h - * @see_also: #GIcon, #GThemedIcon - * - * Extends the #GIcon interface and adds the ability to - * load icons from streams. - */ - - -/** - * SECTION:gmemoryinputstream - * @short_description: Streaming input operations on memory chunks - * @include: gio/gio.h - * @see_also: #GMemoryOutputStream - * - * #GMemoryInputStream is a class for using arbitrary - * memory chunks as input for GIO streaming input operations. - * - * As of GLib 2.34, #GMemoryInputStream implements - * #GPollableInputStream. - */ - - -/** - * SECTION:gmemorymonitor - * @title: GMemoryMonitor - * @short_description: Memory usage monitor - * @include: gio/gio.h - * - * #GMemoryMonitor will monitor system memory and suggest to the application - * when to free memory so as to leave more room for other applications. - * It is implemented on Linux using the [Low Memory Monitor](https://gitlab.freedesktop.org/hadess/low-memory-monitor/) - * ([API documentation](https://hadess.pages.freedesktop.org/low-memory-monitor/)). - * - * There is also an implementation for use inside Flatpak sandboxes. - * - * Possible actions to take when the signal is received are: - * - * - Free caches - * - Save files that haven't been looked at in a while to disk, ready to be reopened when needed - * - Run a garbage collection cycle - * - Try and compress fragmented allocations - * - Exit on idle if the process has no reason to stay around - * - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to - * the kernel (if supported by your libc) - * - * Note that some actions may not always improve system performance, and so - * should be profiled for your application. `malloc_trim()`, for example, may - * make future heap allocations slower (due to releasing cached heap pages back - * to the kernel). - * - * See #GMemoryMonitorWarningLevel for details on the various warning levels. - * - * |[ - * static void - * warning_cb (GMemoryMonitor *m, GMemoryMonitorWarningLevel level) - * { - * g_debug ("Warning level: %d", level); - * if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) - * drop_caches (); - * } - * - * static GMemoryMonitor * - * monitor_low_memory (void) - * { - * GMemoryMonitor *m; - * m = g_memory_monitor_dup_default (); - * g_signal_connect (G_OBJECT (m), "low-memory-warning", - * G_CALLBACK (warning_cb), NULL); - * return m; - * } - * ]| - * - * Don't forget to disconnect the #GMemoryMonitor::low-memory-warning - * signal, and unref the #GMemoryMonitor itself when exiting. - * - * Since: 2.64 - */ - - -/** - * SECTION:gmemoryoutputstream - * @short_description: Streaming output operations on memory chunks - * @include: gio/gio.h - * @see_also: #GMemoryInputStream - * - * #GMemoryOutputStream is a class for using arbitrary - * memory chunks as output for GIO streaming output operations. - * - * As of GLib 2.34, #GMemoryOutputStream trivially implements - * #GPollableOutputStream: it always polls as ready. - */ - - -/** - * SECTION:gmenu - * @title: GMenu - * @short_description: A simple implementation of GMenuModel - * @include: gio/gio.h - * - * #GMenu is a simple implementation of #GMenuModel. - * You populate a #GMenu by adding #GMenuItem instances to it. - * - * There are some convenience functions to allow you to directly - * add items (avoiding #GMenuItem) for the common cases. To add - * a regular item, use g_menu_insert(). To add a section, use - * g_menu_insert_section(). To add a submenu, use - * g_menu_insert_submenu(). - */ - - -/** - * SECTION:gmenuexporter - * @title: GMenuModel exporter - * @short_description: Export GMenuModels on D-Bus - * @include: gio/gio.h - * @see_also: #GMenuModel, #GDBusMenuModel - * - * These functions support exporting a #GMenuModel on D-Bus. - * The D-Bus interface that is used is a private implementation - * detail. - * - * To access an exported #GMenuModel remotely, use - * g_dbus_menu_model_get() to obtain a #GDBusMenuModel. - */ - - -/** - * SECTION:gmenumodel - * @title: GMenuModel - * @short_description: An abstract class representing the contents of a menu - * @include: gio/gio.h - * @see_also: #GActionGroup - * - * #GMenuModel represents the contents of a menu -- an ordered list of - * menu items. The items are associated with actions, which can be - * activated through them. Items can be grouped in sections, and may - * have submenus associated with them. Both items and sections usually - * have some representation data, such as labels or icons. The type of - * the associated action (ie whether it is stateful, and what kind of - * state it has) can influence the representation of the item. - * - * The conceptual model of menus in #GMenuModel is hierarchical: - * sections and submenus are again represented by #GMenuModels. - * Menus themselves do not define their own roles. Rather, the role - * of a particular #GMenuModel is defined by the item that references - * it (or, in the case of the 'root' menu, is defined by the context - * in which it is used). - * - * As an example, consider the visible portions of this menu: - * - * ## An example menu # {#menu-example} - * - * ![](menu-example.png) - * - * There are 8 "menus" visible in the screenshot: one menubar, two - * submenus and 5 sections: - * - * - the toplevel menubar (containing 4 items) - * - the View submenu (containing 3 sections) - * - the first section of the View submenu (containing 2 items) - * - the second section of the View submenu (containing 1 item) - * - the final section of the View submenu (containing 1 item) - * - the Highlight Mode submenu (containing 2 sections) - * - the Sources section (containing 2 items) - * - the Markup section (containing 2 items) - * - * The [example][menu-model] illustrates the conceptual connection between - * these 8 menus. Each large block in the figure represents a menu and the - * smaller blocks within the large block represent items in that menu. Some - * items contain references to other menus. - * - * ## A menu example # {#menu-model} - * - * ![](menu-model.png) - * - * Notice that the separators visible in the [example][menu-example] - * appear nowhere in the [menu model][menu-model]. This is because - * separators are not explicitly represented in the menu model. Instead, - * a separator is inserted between any two non-empty sections of a menu. - * Section items can have labels just like any other item. In that case, - * a display system may show a section header instead of a separator. - * - * The motivation for this abstract model of application controls is - * that modern user interfaces tend to make these controls available - * outside the application. Examples include global menus, jumplists, - * dash boards, etc. To support such uses, it is necessary to 'export' - * information about actions and their representation in menus, which - * is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter] - * and the [GMenuModel exporter][gio-GMenuModel-exporter] do for - * #GActionGroup and #GMenuModel. The client-side counterparts to - * make use of the exported information are #GDBusActionGroup and - * #GDBusMenuModel. - * - * The API of #GMenuModel is very generic, with iterators for the - * attributes and links of an item, see g_menu_model_iterate_item_attributes() - * and g_menu_model_iterate_item_links(). The 'standard' attributes and - * link types have predefined names: %G_MENU_ATTRIBUTE_LABEL, - * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION - * and %G_MENU_LINK_SUBMENU. - * - * Items in a #GMenuModel represent active controls if they refer to - * an action that can get activated when the user interacts with the - * menu item. The reference to the action is encoded by the string id - * in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely - * identifies an action in an action group. Which action group(s) provide - * actions depends on the context in which the menu model is used. - * E.g. when the model is exported as the application menu of a - * #GtkApplication, actions can be application-wide or window-specific - * (and thus come from two different action groups). By convention, the - * application-wide actions have names that start with "app.", while the - * names of window-specific actions start with "win.". - * - * While a wide variety of stateful actions is possible, the following - * is the minimum that is expected to be supported by all users of exported - * menu information: - * - an action with no parameter type and no state - * - an action with no parameter type and boolean state - * - an action with string parameter type and string state - * - * ## Stateless - * - * A stateless action typically corresponds to an ordinary menu item. - * - * Selecting such a menu item will activate the action (with no parameter). - * - * ## Boolean State - * - * An action with a boolean state will most typically be used with a "toggle" - * or "switch" menu item. The state can be set directly, but activating the - * action (with no parameter) results in the state being toggled. - * - * Selecting a toggle menu item will activate the action. The menu item should - * be rendered as "checked" when the state is true. - * - * ## String Parameter and State - * - * Actions with string parameters and state will most typically be used to - * represent an enumerated choice over the items available for a group of - * radio menu items. Activating the action with a string parameter is - * equivalent to setting that parameter as the state. - * - * Radio menu items, in addition to being associated with the action, will - * have a target value. Selecting that menu item will result in activation - * of the action with the target value as the parameter. The menu item should - * be rendered as "selected" when the state of the action is equal to the - * target value of the menu item. - */ - - -/** - * SECTION:gmount - * @short_description: Mount management - * @include: gio/gio.h - * @see_also: GVolume, GUnixMountEntry, GUnixMountPoint - * - * The #GMount interface represents user-visible mounts. Note, when - * porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume. - * - * #GMount is a "mounted" filesystem that you can access. Mounted is in - * quotes because it's not the same as a unix mount, it might be a gvfs - * mount, but you can still access the files on it if you use GIO. Might or - * might not be related to a volume object. - * - * Unmounting a #GMount instance is an asynchronous operation. For - * more information about asynchronous operations, see #GAsyncResult - * 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 - * #GAsyncResult structure will be passed to the callback. That - * callback should then call g_mount_unmount_with_operation_finish() with the #GMount - * and the #GAsyncResult data to see if the operation was completed - * successfully. If an @error is present when g_mount_unmount_with_operation_finish() - * is called, then it will be filled with any error information. - */ - - -/** - * SECTION:gmountoperation - * @short_description: Object used for authentication and user interaction - * @include: gio/gio.h - * - * #GMountOperation provides a mechanism for interacting with the user. - * It can be used for authenticating mountable operations, such as loop - * mounting files, hard drive partitions or server locations. It can - * also be used to ask the user questions or show a list of applications - * preventing unmount or eject operations from completing. - * - * Note that #GMountOperation is used for more than just #GMount - * objects – for example it is also used in g_drive_start() and - * g_drive_stop(). - * - * Users should instantiate a subclass of this that implements all the - * various callbacks to show the required dialogs, such as - * #GtkMountOperation. If no user interaction is desired (for example - * when automounting filesystems at login time), usually %NULL can be - * passed, see each method taking a #GMountOperation for details. - * - * The term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. - * [TrueCrypt](https://en.wikipedia.org/wiki/TrueCrypt) is a discontinued system for - * encrypting file containers, partitions or whole disks, typically used with Windows. - * [VeraCrypt](https://www.veracrypt.fr/) is a maintained fork of TrueCrypt with various - * improvements and auditing fixes. - */ - - -/** - * SECTION:gnativesocketaddress - * @short_description: Native GSocketAddress - * @include: gio/gio.h - * - * A socket address of some unknown native type. - */ - - -/** - * SECTION:gnetworkaddress - * @short_description: A GSocketConnectable for resolving hostnames - * @include: gio/gio.h - * - * #GNetworkAddress provides an easy way to resolve a hostname and - * then attempt to connect to that host, handling the possibility of - * multiple IP addresses and multiple address families. - * - * The enumeration results of resolved addresses *may* be cached as long - * as this object is kept alive which may have unexpected results if - * alive for too long. - * - * See #GSocketConnectable for an example of using the connectable - * interface. - */ - - -/** - * SECTION:gnetworking - * @title: gnetworking.h - * @short_description: System networking includes - * @include: gio/gnetworking.h - * - * The `` 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 GNU libc, certain non-portable functions are only visible - * in the headers if you define %_GNU_SOURCE before including them. Note - * that this symbol must be defined before including any headers, or it - * may not take effect. - */ - - -/** - * SECTION:gnetworkmonitor - * @title: GNetworkMonitor - * @short_description: Network status monitor - * @include: gio/gio.h - * - * #GNetworkMonitor provides an easy-to-use cross-platform API - * for monitoring network connectivity. On Linux, the available - * implementations are based on the kernel's netlink interface and - * on NetworkManager. - * - * There is also an implementation for use inside Flatpak sandboxes. - */ - - -/** - * SECTION:gnetworkservice - * @short_description: A GSocketConnectable for resolving SRV records - * @include: gio/gio.h - * - * Like #GNetworkAddress does with hostnames, #GNetworkService - * provides an easy way to resolve a SRV record, and then attempt to - * connect to one of the hosts that implements that service, handling - * service priority/weighting, multiple IP addresses, and multiple - * address families. - * - * See #GSrvTarget for more information about SRV records, and see - * #GSocketConnectable for an example of using the connectable - * interface. - */ - - -/** - * SECTION:gnotification - * @short_description: User Notifications (pop up messages) - * @include: gio/gio.h - * - * #GNotification is a mechanism for creating a notification to be shown - * to the user -- typically as a pop-up notification presented by the - * desktop environment shell. - * - * The key difference between #GNotification and other similar APIs is - * that, if supported by the desktop environment, notifications sent - * with #GNotification will persist after the application has exited, - * and even across system reboots. - * - * Since the user may click on a notification while the application is - * not running, applications using #GNotification should be able to be - * started as a D-Bus service, using #GApplication. - * - * In order for #GNotification to work, the application must have installed - * a `.desktop` file. For example: - * |[ - * [Desktop Entry] - * Name=Test Application - * Comment=Description of what Test Application does - * Exec=gnome-test-application - * Icon=org.gnome.TestApplication - * Terminal=false - * Type=Application - * Categories=GNOME;GTK;TestApplication Category; - * StartupNotify=true - * DBusActivatable=true - * X-GNOME-UsesNotifications=true - * ]| - * - * The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center - * that this application uses notifications, so it can be listed in the - * Control Center’s ‘Notifications’ panel. - * - * The `.desktop` file must be named as `org.gnome.TestApplication.desktop`, - * where `org.gnome.TestApplication` is the ID passed to g_application_new(). - * - * User interaction with a notification (either the default action, or - * buttons) must be associated with actions on the application (ie: - * "app." actions). It is not possible to route user interaction - * through the notification itself, because the object will not exist if - * the application is autostarted as a result of a notification being - * clicked. - * - * A notification can be sent with g_application_send_notification(). - * - * Since: 2.40 - */ - - -/** - * SECTION:goutputstream - * @short_description: Base class for implementing streaming output - * @include: gio/gio.h - * - * #GOutputStream has functions to write to a stream (g_output_stream_write()), - * to close a stream (g_output_stream_close()) and to flush pending writes - * (g_output_stream_flush()). - * - * To copy the content of an input stream to an output stream without - * manually handling the reads and writes, use g_output_stream_splice(). - * - * See the documentation for #GIOStream for details of thread safety of - * streaming APIs. - * - * All of these functions have async variants too. - */ - - -/** - * SECTION:gpermission - * @title: GPermission - * @short_description: An object representing the permission - * to perform a certain action - * @include: gio/gio.h - * - * A #GPermission represents the status of the caller's permission to - * perform a certain action. - * - * You can query if the action is currently allowed and if it is - * possible to acquire the permission so that the action will be allowed - * in the future. - * - * There is also an API to actually acquire the permission and one to - * release it. - * - * As an example, a #GPermission might represent the ability for the - * user to write to a #GSettings object. This #GPermission object could - * then be used to decide if it is appropriate to show a "Click here to - * unlock" button in a dialog and to provide the mechanism to invoke - * when that button is clicked. - */ - - -/** - * SECTION:gpollableinputstream - * @short_description: Interface for pollable input streams - * @include: gio/gio.h - * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased - * - * #GPollableInputStream is implemented by #GInputStreams that - * can be polled for readiness to read. This can be used when - * interfacing with a non-GIO API that expects - * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. - * - * Since: 2.28 - */ - - -/** - * SECTION:gpollableoutputstream - * @short_description: Interface for pollable output streams - * @include: gio/gio.h - * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream - * - * #GPollableOutputStream is implemented by #GOutputStreams that - * can be polled for readiness to write. This can be used when - * interfacing with a non-GIO API that expects - * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. - * - * Since: 2.28 - */ - - -/** - * SECTION:gpollableutils - * @short_description: Utilities for pollable streams - * @include: gio/gio.h - * - * Utility functions for #GPollableInputStream and - * #GPollableOutputStream implementations. - */ - - -/** - * SECTION:gpowerprofilemonitor - * @title: GPowerProfileMonitor - * @short_description: Power profile monitor - * @include: gio/gio.h - * - * #GPowerProfileMonitor makes it possible for applications as well as OS components - * to monitor system power profiles and act upon them. It currently only exports - * whether the system is in “Power Saver” mode (known as “Low Power” mode on - * some systems). - * - * When in “Low Power” mode, it is recommended that applications: - * - disabling automatic downloads - * - reduce the rate of refresh from online sources such as calendar or - * email synchronisation - * - if the application has expensive visual effects, reduce them - * - * It is also likely that OS components providing services to applications will - * lower their own background activity, for the sake of the system. - * - * There are a variety of tools that exist for power consumption analysis, but those - * usually depend on the OS and hardware used. On Linux, one could use `upower` to - * monitor the battery discharge rate, `powertop` to check on the background activity - * or activity at all), `sysprof` to inspect CPU usage, and `intel_gpu_time` to - * profile GPU usage. - * - * Don't forget to disconnect the #GPowerProfileMonitor::notify::power-saver-enabled - * signal, and unref the #GPowerProfileMonitor itself when exiting. - * - * Since: 2.70 - */ - - -/** - * SECTION:gpropertyaction - * @title: GPropertyAction - * @short_description: A GAction reflecting a GObject property - * @include: gio/gio.h - * - * 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 is 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 - * @include: gio/gio.h - * - * A #GProxy handles connecting to a remote host via a given type of - * proxy server. It is implemented by the 'gio-proxy' extension point. - * The extensions are named after their proxy protocol name. As an - * example, a SOCKS5 proxy implementation can be retrieved with the - * name 'socks5' using the function - * g_io_extension_point_get_extension_by_name(). - * - * Since: 2.26 - */ - - -/** - * SECTION:gproxyaddress - * @short_description: An internet address with proxy information - * @include: gio/gio.h - * - * Support for proxied #GInetSocketAddress. - */ - - -/** - * SECTION:gproxyaddressenumerator - * @short_description: Proxy wrapper enumerator for socket addresses - * @include: gio/gio.h - * - * #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which - * takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator - * and wraps them in #GProxyAddress instances, using the given - * #GProxyAddressEnumerator:proxy-resolver. - * - * This enumerator will be returned (for example, by - * g_socket_connectable_enumerate()) as appropriate when a proxy is configured; - * there should be no need to manually wrap a #GSocketAddressEnumerator instance - * with one. - */ - - -/** - * SECTION:gproxyresolver - * @short_description: Asynchronous and cancellable network proxy resolver - * @include: gio/gio.h - * - * #GProxyResolver provides synchronous and asynchronous network proxy - * resolution. #GProxyResolver is used within #GSocketClient through - * the method g_socket_connectable_proxy_enumerate(). - * - * Implementations of #GProxyResolver based on libproxy and GNOME settings can - * be found in glib-networking. GIO comes with an implementation for use inside - * Flatpak portals. - */ - - -/** - * SECTION:gremoteactiongroup - * @title: GRemoteActionGroup - * @short_description: A GActionGroup that interacts with other processes - * @include: gio/gio.h - * - * The GRemoteActionGroup interface is implemented by #GActionGroup - * instances that either transmit action invocations to other processes - * or receive action invocations in the local process from other - * processes. - * - * The interface has `_full` variants of the two - * methods on #GActionGroup used to activate actions: - * g_action_group_activate_action() and - * g_action_group_change_action_state(). These variants allow a - * "platform data" #GVariant to be specified: a dictionary providing - * context for the action invocation (for example: timestamps, startup - * notification IDs, etc). - * - * #GDBusActionGroup implements #GRemoteActionGroup. This provides a - * mechanism to send platform data for action invocations over D-Bus. - * - * Additionally, g_dbus_connection_export_action_group() will check if - * the exported #GActionGroup implements #GRemoteActionGroup and use the - * `_full` variants of the calls if available. This - * provides a mechanism by which to receive platform data for action - * invocations that arrive by way of D-Bus. - * - * Since: 2.32 - */ - - -/** - * SECTION:gresolver - * @short_description: Asynchronous and cancellable DNS resolver - * @include: gio/gio.h - * - * #GResolver provides cancellable synchronous and asynchronous DNS - * resolution, for hostnames (g_resolver_lookup_by_address(), - * g_resolver_lookup_by_name() and their async variants) and SRV - * (service) records (g_resolver_lookup_service()). - * - * #GNetworkAddress and #GNetworkService provide wrappers around - * #GResolver functionality that also implement #GSocketConnectable, - * making it easy to connect to a remote host/service. - */ - - -/** - * SECTION:gresource - * @short_description: Resource framework - * @include: gio/gio.h - * - * Applications and libraries often contain binary or textual data that is - * really part of the application, rather than user data. For instance - * #GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files, - * icons, etc. These are often shipped as files in `$datadir/appname`, or - * manually included as literal strings in the code. - * - * The #GResource API and the [glib-compile-resources][glib-compile-resources] program - * provide a convenient and efficient alternative to this which has some nice properties. You - * maintain the files as normal files, so its easy to edit them, but during the build the files - * are combined into a binary bundle that is linked into the executable. This means that loading - * the resource files are efficient (as they are already in memory, shared with other instances) and - * simple (no need to check for things like I/O errors or locate the files in the filesystem). It - * also makes it easier to create relocatable applications. - * - * Resource files can also be marked as compressed. Such files will be included in the resource bundle - * in a compressed form, but will be automatically uncompressed when the resource is used. This - * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away. - * - * Resource files can also be marked to be preprocessed, by setting the value of the - * `preprocess` attribute to a comma-separated list of preprocessing options. - * The only options currently supported are: - * - * `xml-stripblanks` which will use the xmllint command - * to strip ignorable whitespace from the XML file. For this to work, - * the `XMLLINT` environment variable must be set to the full path to - * the xmllint executable, or xmllint must be in the `PATH`; otherwise - * the preprocessing step is skipped. - * - * `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the - * `gdk-pixbuf-pixdata` command to convert images to the #GdkPixdata format, - * which allows you to create pixbufs directly using the data inside the - * resource file, rather than an (uncompressed) copy of it. For this, the - * `gdk-pixbuf-pixdata` program must be in the `PATH`, or the - * `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the - * `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will abort. - * `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as #GResource - * supports embedding modern image formats just as well. Instead of using it, - * embed a PNG or SVG file in your #GResource. - * - * `json-stripblanks` which will use the `json-glib-format` command to strip - * ignorable whitespace from the JSON file. For this to work, the - * `JSON_GLIB_FORMAT` environment variable must be set to the full path to the - * `json-glib-format` executable, or it must be in the `PATH`; - * otherwise the preprocessing step is skipped. In addition, at least version - * 1.6 of `json-glib-format` is required. - * - * Resource files will be exported in the GResource namespace using the - * combination of the given `prefix` and the filename from the `file` element. - * The `alias` attribute can be used to alter the filename to expose them at a - * different location in the resource namespace. Typically, this is used to - * include files from a different source directory without exposing the source - * directory in the resource namespace, as in the example below. - * - * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program - * which takes an XML file that describes the bundle, and a set of files that the XML references. These - * are combined into a binary resource bundle. - * - * An example resource description: - * |[ - * - * - * - * data/splashscreen.png - * dialog.ui - * menumarkup.xml - * data/example.css - * - * - * ]| - * - * This will create a resource bundle with the following files: - * |[ - * /org/gtk/Example/data/splashscreen.png - * /org/gtk/Example/dialog.ui - * /org/gtk/Example/menumarkup.xml - * /org/gtk/Example/example.css - * ]| - * - * Note that all resources in the process share the same namespace, so use Java-style - * path prefixes (like in the above example) to avoid conflicts. - * - * You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a - * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and - * --generate-header arguments to create a source file and header to link directly into your application. - * This will generate `get_resource()`, `register_resource()` and - * `unregister_resource()` functions, prefixed by the `--c-name` argument passed - * to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns - * the generated #GResource object. The register and unregister functions - * register the resource so its files can be accessed using - * g_resources_lookup_data(). - * - * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by - * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer - * to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access - * the resource data. - * - * Some higher-level APIs, such as #GtkApplication, will automatically load - * resources from certain well-known paths in the resource namespace as a - * convenience. See the documentation for those APIs for details. - * - * There are two forms of the generated source, the default version uses the compiler support for constructor - * and destructor functions (where available) to automatically create and register the #GResource on startup - * or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created - * instead. This requires an explicit initialization call in your application/library, but it works on all platforms, - * even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.) - * - * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries - * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away - * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses - * are for your own resources, and resource data is often used once, during parsing, and then released. - * - * When debugging a program or testing a change to an installed version, it is often useful to be able to - * replace resources in the program or library, without recompiling, for debugging or quick hacking and testing - * purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay - * resources with replacements from the filesystem. It is a %G_SEARCHPATH_SEPARATOR-separated list of substitutions to perform - * during resource lookups. It is ignored when running in a setuid process. - * - * A substitution has the form - * - * |[ - * /org/gtk/libgtk=/home/desrt/gtk-overlay - * ]| - * - * The part before the `=` is the resource subpath for which the overlay applies. The part after is a - * filesystem path which contains files and subdirectories as you would like to be loaded as resources with the - * equivalent names. - * - * In the example above, if an application tried to load a resource with the resource path - * `/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path - * `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an - * overlay, not an outright replacement, which means that if a file is not found at that path, the built-in - * version will be used instead. Whiteouts are not currently supported. - * - * Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after - * the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the - * location of a single resource with an individual file. - * - * Since: 2.32 - */ - - -/** - * SECTION:gseekable - * @short_description: Stream seeking interface - * @include: gio/gio.h - * @see_also: #GInputStream, #GOutputStream - * - * #GSeekable is implemented by streams (implementations of - * #GInputStream or #GOutputStream) that support seeking. - * - * Seekable streams largely fall into two categories: resizable and - * fixed-size. - * - * #GSeekable on fixed-sized streams is approximately the same as POSIX - * lseek() on a block device (for example: attempting to seek past the - * end of the device is an error). Fixed streams typically cannot be - * truncated. - * - * #GSeekable on resizable streams is approximately the same as POSIX - * lseek() on a normal file. Seeking past the end and writing data will - * usually cause the stream to resize by introducing zero bytes. - */ - - -/** - * SECTION:gsettings - * @short_description: High-level API for application settings - * @include: gio/gio.h - * - * The #GSettings class provides a convenient API for storing and retrieving - * application settings. - * - * Reads and writes can be considered to be non-blocking. Reading - * settings with #GSettings is typically extremely fast: on - * approximately the same order of magnitude (but slower than) a - * #GHashTable lookup. Writing settings is also extremely fast in terms - * of time to return to your application, but can be extremely expensive - * for other threads and other processes. Many settings backends - * (including dconf) have lazy initialisation which means in the common - * case of the user using their computer without modifying any settings - * a lot of work can be avoided. For dconf, the D-Bus service doesn't - * even need to be started in this case. For this reason, you should - * only ever modify #GSettings keys in response to explicit user action. - * Particular care should be paid to ensure that modifications are not - * made during startup -- for example, when setting the initial value - * of preferences widgets. The built-in g_settings_bind() functionality - * is careful not to write settings in response to notify signals as a - * result of modifications that it makes to widgets. - * - * When creating a GSettings instance, you have to specify a schema - * that describes the keys in your settings and their types and default - * values, as well as some other information. - * - * Normally, a schema has a fixed path that determines where the settings - * are stored in the conceptual global tree of settings. However, schemas - * can also be '[relocatable][gsettings-relocatable]', i.e. not equipped with - * a fixed path. This is - * useful e.g. when the schema describes an 'account', and you want to be - * able to store a arbitrary number of accounts. - * - * Paths must start with and end with a forward slash character ('/') - * and must not contain two sequential slash characters. Paths should - * be chosen based on a domain name associated with the program or - * library to which the settings belong. Examples of paths are - * "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/". - * Paths should not start with "/apps/", "/desktop/" or "/system/" as - * they often did in GConf. - * - * Unlike other configuration systems (like GConf), GSettings does not - * restrict keys to basic types like strings and numbers. GSettings stores - * values as #GVariant, and allows any #GVariantType for keys. Key names - * are restricted to lowercase characters, numbers and '-'. Furthermore, - * the names must begin with a lowercase character, must not end - * with a '-', and must not contain consecutive dashes. - * - * Similar to GConf, the default values in GSettings schemas can be - * localized, but the localized values are stored in gettext catalogs - * and looked up with the domain that is specified in the - * `gettext-domain` attribute of the or - * elements and the category that is specified in the `l10n` attribute of - * the element. The string which is translated includes all text in - * the element, including any surrounding quotation marks. - * - * The `l10n` attribute must be set to `messages` or `time`, and sets the - * [locale category for - * translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1). - * The `messages` category should be used by default; use `time` for - * translatable date or time formats. A translation comment can be added as an - * XML comment immediately above the element — it is recommended to - * add these comments to aid translators understand the meaning and - * implications of the default value. An optional translation `context` - * attribute can be set on the element to disambiguate multiple - * defaults which use the same string. - * - * For example: - * |[ - * - * ['bad', 'words'] - * ]| - * - * Translations of default values must remain syntactically valid serialized - * #GVariants (e.g. retaining any surrounding quotation marks) or runtime - * errors will occur. - * - * GSettings uses schemas in a compact binary form that is created - * by the [glib-compile-schemas][glib-compile-schemas] - * utility. The input is a schema description in an XML format. - * - * A DTD for the gschema XML format can be found here: - * [gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd) - * - * The [glib-compile-schemas][glib-compile-schemas] tool expects schema - * files to have the extension `.gschema.xml`. - * - * At runtime, schemas are identified by their id (as specified in the - * id attribute of the element). The convention for schema - * ids is to use a dotted name, similar in style to a D-Bus bus name, - * e.g. "org.gnome.SessionManager". In particular, if the settings are - * for a specific service that owns a D-Bus bus name, the D-Bus bus name - * and schema id should match. For schemas which deal with settings not - * associated with one named application, the id should not use - * StudlyCaps, e.g. "org.gnome.font-rendering". - * - * In addition to #GVariant types, keys can have types that have - * enumerated types. These can be described by a , - * or element, as seen in the - * [example][schema-enumerated]. The underlying type of such a key - * is string, but you can use g_settings_get_enum(), g_settings_set_enum(), - * g_settings_get_flags(), g_settings_set_flags() access the numeric values - * corresponding to the string value of enum and flags keys. - * - * An example for default value: - * |[ - * - * - * - * - * "Hello, earthlings" - * A greeting - * - * Greeting of the invading martians - * - * - * - * - * (20,30) - * - * - * - * "" - * Empty strings have to be provided in GVariant form - * - * - * - * - * ]| - * - * An example for ranges, choices and enumerated types: - * |[ - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * 10 - * - * - * - * - * - * - * - * - * - * - * - * - * 'Joe' - * - * - * - * 'first' - * - * - * - * ["flag1","flag2"] - * - * - * - * ]| - * - * ## Vendor overrides - * - * Default values are defined in the schemas that get installed by - * an application. Sometimes, it is necessary for a vendor or distributor - * to adjust these defaults. Since patching the XML source for the schema - * is inconvenient and error-prone, - * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor - * override' files. These are keyfiles in the same directory as the XML - * schema sources which can override default values. The schema id serves - * as the group name in the key file, and the values are expected in - * serialized GVariant form, as in the following example: - * |[ - * [org.gtk.Example] - * key1='string' - * key2=1.5 - * ]| - * - * glib-compile-schemas expects schema files to have the extension - * `.gschema.override`. - * - * ## Binding - * - * A very convenient feature of GSettings lets you bind #GObject properties - * directly to settings, using g_settings_bind(). Once a GObject property - * has been bound to a setting, changes on either side are automatically - * propagated to the other side. GSettings handles details like mapping - * between GObject and GVariant types, and preventing infinite cycles. - * - * This makes it very easy to hook up a preferences dialog to the - * underlying settings. To make this even more convenient, GSettings - * looks for a boolean property with the name "sensitivity" and - * automatically binds it to the writability of the bound setting. - * If this 'magic' gets in the way, it can be suppressed with the - * #G_SETTINGS_BIND_NO_SENSITIVITY flag. - * - * ## Relocatable schemas # {#gsettings-relocatable} - * - * A relocatable schema is one with no `path` attribute specified on its - * element. By using g_settings_new_with_path(), a #GSettings object - * can be instantiated for a relocatable schema, assigning a path to the - * instance. Paths passed to g_settings_new_with_path() will typically be - * constructed dynamically from a constant prefix plus some form of instance - * identifier; but they must still be valid GSettings paths. Paths could also - * be constant and used with a globally installed schema originating from a - * dependency library. - * - * For example, a relocatable schema could be used to store geometry information - * for different windows in an application. If the schema ID was - * `org.foo.MyApp.Window`, it could be instantiated for paths - * `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`, - * `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known - * they can be specified as elements in the parent schema, e.g.: - * |[ - * - * - * - * ]| - * - * ## Build system integration # {#gsettings-build-system} - * - * GSettings comes with autotools integration to simplify compiling and - * installing schemas. To add GSettings support to an application, add the - * following to your `configure.ac`: - * |[ - * GLIB_GSETTINGS - * ]| - * - * In the appropriate `Makefile.am`, use the following snippet to compile and - * install the named schema: - * |[ - * gsettings_SCHEMAS = org.foo.MyApp.gschema.xml - * EXTRA_DIST = $(gsettings_SCHEMAS) - * - * @GSETTINGS_RULES@ - * ]| - * - * No changes are needed to the build system to mark a schema XML file for - * translation. Assuming it sets the `gettext-domain` attribute, a schema may - * be marked for translation by adding it to `POTFILES.in`, assuming gettext - * 0.19 is in use (the preferred method for translation): - * |[ - * data/org.foo.MyApp.gschema.xml - * ]| - * - * Alternatively, if intltool 0.50.1 is in use: - * |[ - * [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml - * ]| - * - * GSettings will use gettext to look up translations for the and - * elements, and also any elements which have a `l10n` - * attribute set. Translations must not be included in the `.gschema.xml` file - * by the build system, for example by using intltool XML rules with a - * `.gschema.xml.in` template. - * - * If an enumerated type defined in a C header file is to be used in a GSettings - * schema, it can either be defined manually using an element in the - * schema XML, or it can be extracted automatically from the C header. This - * approach is preferred, as it ensures the two representations are always - * synchronised. To do so, add the following to the relevant `Makefile.am`: - * |[ - * gsettings_ENUM_NAMESPACE = org.foo.MyApp - * gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h - * ]| - * - * `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files, - * which are specified in `gsettings_ENUM_FILES`. This will generate a - * `org.foo.MyApp.enums.xml` file containing the extracted enums, which will be - * automatically included in the schema compilation, install and uninstall - * rules. It should not be committed to version control or included in - * `EXTRA_DIST`. - */ - - -/** - * SECTION:gsettingsbackend - * @title: GSettingsBackend - * @short_description: Interface for settings backend implementations - * @include: gio/gsettingsbackend.h - * @see_also: #GSettings, #GIOExtensionPoint - * - * The #GSettingsBackend interface defines a generic interface for - * non-strictly-typed data that is stored in a hierarchy. To implement - * an alternative storage backend for #GSettings, you need to implement - * the #GSettingsBackend interface and then make it implement the - * extension point #G_SETTINGS_BACKEND_EXTENSION_POINT_NAME. - * - * The interface defines methods for reading and writing values, a - * method for determining if writing of certain values will fail - * (lockdown) and a change notification mechanism. - * - * The semantics of the interface are very precisely defined and - * implementations must carefully adhere to the expectations of - * callers that are documented on each of the interface methods. - * - * Some of the #GSettingsBackend functions accept or return a #GTree. - * These trees always have strings as keys and #GVariant as values. - * g_settings_backend_create_tree() is a convenience function to create - * suitable trees. - * - * The #GSettingsBackend API is exported to allow third-party - * implementations, but does not carry the same stability guarantees - * as the public GIO API. For this reason, you have to define the - * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including - * `gio/gsettingsbackend.h`. - */ - - -/** - * SECTION:gsettingsschema - * @short_description: Introspecting and controlling the loading - * of GSettings schemas - * @include: gio/gio.h - * - * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a - * mechanism for advanced control over the loading of schemas and a - * mechanism for introspecting their content. - * - * Plugin loading systems that wish to provide plugins a way to access - * settings face the problem of how to make the schemas for these - * settings visible to GSettings. Typically, a plugin will want to ship - * the schema along with itself and it won't be installed into the - * standard system directories for schemas. - * - * #GSettingsSchemaSource provides a mechanism for dealing with this by - * allowing the creation of a new 'schema source' from which schemas can - * be acquired. This schema source can then become part of the metadata - * associated with the plugin and queried whenever the plugin requires - * access to some settings. - * - * Consider the following example: - * - * |[ - * typedef struct - * { - * ... - * GSettingsSchemaSource *schema_source; - * ... - * } Plugin; - * - * Plugin * - * initialise_plugin (const gchar *dir) - * { - * Plugin *plugin; - * - * ... - * - * plugin->schema_source = - * g_settings_schema_source_new_from_directory (dir, - * g_settings_schema_source_get_default (), FALSE, NULL); - * - * ... - * - * return plugin; - * } - * - * ... - * - * GSettings * - * plugin_get_settings (Plugin *plugin, - * const gchar *schema_id) - * { - * GSettingsSchema *schema; - * - * if (schema_id == NULL) - * schema_id = plugin->identifier; - * - * schema = g_settings_schema_source_lookup (plugin->schema_source, - * schema_id, FALSE); - * - * if (schema == NULL) - * { - * ... disable the plugin or abort, etc ... - * } - * - * return g_settings_new_full (schema, NULL, NULL); - * } - * ]| - * - * The code above shows how hooks should be added to the code that - * initialises (or enables) the plugin to create the schema source and - * how an API can be added to the plugin system to provide a convenient - * way for the plugin to access its settings, using the schemas that it - * ships. - * - * From the standpoint of the plugin, it would need to ensure that it - * ships a gschemas.compiled file as part of itself, and then simply do - * the following: - * - * |[ - * { - * GSettings *settings; - * gint some_value; - * - * settings = plugin_get_settings (self, NULL); - * some_value = g_settings_get_int (settings, "some-value"); - * ... - * } - * ]| - * - * It's also possible that the plugin system expects the schema source - * files (ie: .gschema.xml files) instead of a gschemas.compiled file. - * In that case, the plugin loading system must compile the schemas for - * itself before attempting to create the settings source. - * - * Since: 2.32 - */ - - -/** - * SECTION:gsimpleaction - * @title: GSimpleAction - * @short_description: A simple GAction implementation - * @include: gio/gio.h - * - * A #GSimpleAction is the obvious simple implementation of the #GAction - * interface. This is the easiest way to create an action for purposes of - * adding it to a #GSimpleActionGroup. - * - * See also #GtkAction. - */ - - -/** - * SECTION:gsimpleactiongroup - * @title: GSimpleActionGroup - * @short_description: A simple GActionGroup implementation - * @include: gio/gio.h - * - * #GSimpleActionGroup is a hash table filled with #GAction objects, - * implementing the #GActionGroup and #GActionMap interfaces. - */ - - -/** - * SECTION:gsimpleasyncresult - * @short_description: Simple asynchronous results implementation - * @include: gio/gio.h - * @see_also: #GAsyncResult, #GTask - * - * As of GLib 2.46, #GSimpleAsyncResult is deprecated in favor of - * #GTask, which provides a simpler API. - * - * #GSimpleAsyncResult implements #GAsyncResult. - * - * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error - * reporting, operation cancellation and the final state of an operation, - * completely transparent to the application. Results can be returned - * as a pointer e.g. for functions that return data that is collected - * asynchronously, a boolean value for checking the success or failure - * of an operation, or a #gssize for operations which return the number - * of bytes modified by the operation; all of the simple return cases - * are covered. - * - * Most of the time, an application will not need to know of the details - * of this API; it is handled transparently, and any necessary operations - * are handled by #GAsyncResult's interface. However, if implementing a - * new GIO module, for writing language bindings, or for complex - * applications that need better control of how asynchronous operations - * are completed, it is important to understand this functionality. - * - * GSimpleAsyncResults are tagged with the calling function to ensure - * that asynchronous functions and their finishing functions are used - * together correctly. - * - * To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). - * If the result needs to be created for a #GError, use - * g_simple_async_result_new_from_error() or - * g_simple_async_result_new_take_error(). If a #GError is not available - * (e.g. the asynchronous operation's doesn't take a #GError argument), - * but the result still needs to be created for an error condition, use - * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() - * if your application or binding requires passing a variable argument list - * directly), and the error can then be propagated through the use of - * g_simple_async_result_propagate_error(). - * - * An asynchronous operation can be made to ignore a cancellation event by - * calling g_simple_async_result_set_handle_cancellation() with a - * #GSimpleAsyncResult for the operation and %FALSE. This is useful for - * operations that are dangerous to cancel, such as close (which would - * cause a leak if cancelled before being run). - * - * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop, - * or it can use #GThreads. - * g_simple_async_result_complete() will finish an I/O task directly - * from the point where it is called. g_simple_async_result_complete_in_idle() - * will finish it from an idle handler in the - * [thread-default main context][g-main-context-push-thread-default] - * where the #GSimpleAsyncResult was created. - * g_simple_async_result_run_in_thread() will run the job in a - * separate thread and then use - * g_simple_async_result_complete_in_idle() to deliver the result. - * - * To set the results of an asynchronous function, - * g_simple_async_result_set_op_res_gpointer(), - * g_simple_async_result_set_op_res_gboolean(), and - * g_simple_async_result_set_op_res_gssize() - * are provided, setting the operation's result to a gpointer, gboolean, or - * gssize, respectively. - * - * Likewise, to get the result of an asynchronous function, - * g_simple_async_result_get_op_res_gpointer(), - * g_simple_async_result_get_op_res_gboolean(), and - * g_simple_async_result_get_op_res_gssize() are - * provided, getting the operation's result as a gpointer, gboolean, and - * gssize, respectively. - * - * For the details of the requirements implementations must respect, see - * #GAsyncResult. A typical implementation of an asynchronous operation - * using GSimpleAsyncResult looks something like this: - * - * |[ - * static void - * baked_cb (Cake *cake, - * gpointer user_data) - * { - * // In this example, this callback is not given a reference to the cake, - * // so the GSimpleAsyncResult has to take a reference to it. - * GSimpleAsyncResult *result = user_data; - * - * if (cake == NULL) - * g_simple_async_result_set_error (result, - * BAKER_ERRORS, - * BAKER_ERROR_NO_FLOUR, - * "Go to the supermarket"); - * else - * g_simple_async_result_set_op_res_gpointer (result, - * g_object_ref (cake), - * g_object_unref); - * - * - * // In this example, we assume that baked_cb is called as a callback from - * // the mainloop, so it's safe to complete the operation synchronously here. - * // If, however, _baker_prepare_cake () might call its callback without - * // first returning to the mainloop — inadvisable, but some APIs do so — - * // we would need to use g_simple_async_result_complete_in_idle(). - * g_simple_async_result_complete (result); - * g_object_unref (result); - * } - * - * void - * baker_bake_cake_async (Baker *self, - * guint radius, - * GAsyncReadyCallback callback, - * gpointer user_data) - * { - * GSimpleAsyncResult *simple; - * Cake *cake; - * - * if (radius < 3) - * { - * g_simple_async_report_error_in_idle (G_OBJECT (self), - * callback, - * user_data, - * BAKER_ERRORS, - * BAKER_ERROR_TOO_SMALL, - * "%ucm radius cakes are silly", - * radius); - * return; - * } - * - * simple = g_simple_async_result_new (G_OBJECT (self), - * callback, - * user_data, - * baker_bake_cake_async); - * cake = _baker_get_cached_cake (self, radius); - * - * if (cake != NULL) - * { - * g_simple_async_result_set_op_res_gpointer (simple, - * g_object_ref (cake), - * g_object_unref); - * g_simple_async_result_complete_in_idle (simple); - * g_object_unref (simple); - * // Drop the reference returned by _baker_get_cached_cake(); - * // the GSimpleAsyncResult has taken its own reference. - * g_object_unref (cake); - * return; - * } - * - * _baker_prepare_cake (self, radius, baked_cb, simple); - * } - * - * Cake * - * baker_bake_cake_finish (Baker *self, - * GAsyncResult *result, - * GError **error) - * { - * GSimpleAsyncResult *simple; - * Cake *cake; - * - * g_return_val_if_fail (g_simple_async_result_is_valid (result, - * G_OBJECT (self), - * baker_bake_cake_async), - * NULL); - * - * simple = (GSimpleAsyncResult *) result; - * - * if (g_simple_async_result_propagate_error (simple, error)) - * return NULL; - * - * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple)); - * return g_object_ref (cake); - * } - * ]| - */ - - -/** - * SECTION:gsimpleiostream - * @short_description: A wrapper around an input and an output stream. - * @include: gio/gio.h - * @see_also: #GIOStream - * - * GSimpleIOStream creates a #GIOStream from an arbitrary #GInputStream and - * #GOutputStream. This allows any pair of input and output streams to be used - * with #GIOStream methods. - * - * This is useful when you obtained a #GInputStream and a #GOutputStream - * by other means, for instance creating them with platform specific methods as - * g_unix_input_stream_new() or g_win32_input_stream_new(), and you want - * to take advantage of the methods provided by #GIOStream. - * - * Since: 2.44 - */ - - -/** - * SECTION:gsimplepermission - * @title: GSimplePermission - * @short_description: A GPermission that doesn't change value - * @include: gio/gio.h - * - * #GSimplePermission is a trivial implementation of #GPermission that - * represents a permission that is either always or never allowed. The - * value is given at construction and doesn't change. - * - * Calling request or release will result in errors. - */ - - -/** - * 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, [][gio-gnetworking.h] - * - * 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. - * It supports both the UNIX socket implementations and winsock2 on Windows. - * - * #GSocket is the platform independent base upon which the higher level - * network primitives are based. Applications are not typically meant to - * use it directly, but rather through classes like #GSocketClient, - * #GSocketService and #GSocketConnection. However there may be cases where - * direct use of #GSocket is useful. - * - * #GSocket implements the #GInitable interface, so if it is manually constructed - * by e.g. g_object_new() you must call g_initable_init() and check the - * results before using the object. This is done automatically in - * g_socket_new() and g_socket_new_from_fd(), so these functions can return - * %NULL. - * - * Sockets operate in two general modes, blocking or non-blocking. When - * in blocking mode all operations (which don’t take an explicit blocking - * parameter) block until the requested operation - * is finished or there is an error. In non-blocking mode all calls that - * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error. - * To know when a call would successfully run you can call g_socket_condition_check(), - * or g_socket_condition_wait(). You can also use g_socket_create_source() and - * attach it to a #GMainContext to get callbacks when I/O is possible. - * Note that all sockets are always set to non blocking mode in the system, and - * blocking mode is emulated in GSocket. - * - * When working in non-blocking mode applications should always be able to - * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other - * function said that I/O was possible. This can easily happen in case - * of a race condition in the application, but it can also happen for other - * reasons. For instance, on Windows a socket is always seen as writable - * until a write returns %G_IO_ERROR_WOULD_BLOCK. - * - * #GSockets can be either connection oriented or datagram based. - * For connection oriented types you must first establish a connection by - * either connecting to an address or accepting a connection from another - * address. For connectionless socket types the target/source address is - * specified or received in each I/O operation. - * - * All socket file descriptors are set to be close-on-exec. - * - * Note that creating a #GSocket causes the signal %SIGPIPE to be - * ignored for the remainder of the program. If you are writing a - * command-line utility that uses #GSocket, you may need to take into - * account the fact that your program will not automatically be killed - * if it tries to write to %stdout after it has been closed. - * - * Like most other APIs in GLib, #GSocket is not inherently thread safe. To use - * a #GSocket concurrently from multiple threads, you must implement your own - * locking. - * - * Since: 2.22 - */ - - -/** - * SECTION:gsocketaddress - * @short_description: Abstract base class representing endpoints - * for socket communication - * @include: gio/gio.h - * - * #GSocketAddress is the equivalent of struct sockaddr in the BSD - * sockets API. This is an abstract class; use #GInetSocketAddress - * for internet sockets, or #GUnixSocketAddress for UNIX domain sockets. - */ - - -/** - * SECTION:gsocketaddressenumerator - * @short_description: Enumerator for socket addresses - * @include: gio/gio.h - * - * #GSocketAddressEnumerator is an enumerator type for #GSocketAddress - * instances. It is returned by enumeration functions such as - * g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator - * to list each #GSocketAddress which could be used to connect to that - * #GSocketConnectable. - * - * Enumeration is typically a blocking operation, so the asynchronous methods - * g_socket_address_enumerator_next_async() and - * g_socket_address_enumerator_next_finish() should be used where possible. - * - * Each #GSocketAddressEnumerator can only be enumerated once. Once - * g_socket_address_enumerator_next() has returned %NULL, further - * enumeration with that #GSocketAddressEnumerator is not possible, and it can - * be unreffed. - */ - - -/** - * SECTION:gsocketclient - * @short_description: Helper for connecting to a network service - * @include: gio/gio.h - * @see_also: #GSocketConnection, #GSocketListener - * - * #GSocketClient is a lightweight high-level utility class for connecting to - * a network host using a connection oriented socket type. - * - * You create a #GSocketClient object, set any options you want, and then - * call a sync or async connect operation, which returns a #GSocketConnection - * subclass on success. - * - * The type of the #GSocketConnection object returned depends on the type of - * the underlying socket that is in use. For instance, for a TCP/IP connection - * it will be a #GTcpConnection. - * - * As #GSocketClient is a lightweight object, you don't need to cache it. You - * can just create a new one any time you need one. - * - * Since: 2.22 - */ - - -/** - * SECTION:gsocketconnectable - * @short_description: Interface for potential socket endpoints - * @include: gio/gio.h - * - * Objects that describe one or more potential socket endpoints - * implement #GSocketConnectable. Callers can then use - * g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator - * to try out each socket address in turn until one succeeds, as shown - * in the sample code below. - * - * |[ - * MyConnectionType * - * connect_to_host (const char *hostname, - * guint16 port, - * GCancellable *cancellable, - * GError **error) - * { - * MyConnection *conn = NULL; - * GSocketConnectable *addr; - * GSocketAddressEnumerator *enumerator; - * GSocketAddress *sockaddr; - * GError *conn_error = NULL; - * - * addr = g_network_address_new (hostname, port); - * enumerator = g_socket_connectable_enumerate (addr); - * g_object_unref (addr); - * - * // Try each sockaddr until we succeed. Record the first connection error, - * // but not any further ones (since they'll probably be basically the same - * // as the first). - * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error)) - * { - * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error); - * g_object_unref (sockaddr); - * } - * g_object_unref (enumerator); - * - * if (conn) - * { - * if (conn_error) - * { - * // We couldn't connect to the first address, but we succeeded - * // in connecting to a later address. - * g_error_free (conn_error); - * } - * return conn; - * } - * else if (error) - * { - * /// Either initial lookup failed, or else the caller cancelled us. - * if (conn_error) - * g_error_free (conn_error); - * return NULL; - * } - * else - * { - * g_error_propagate (error, conn_error); - * return NULL; - * } - * } - * ]| - */ - - -/** - * SECTION:gsocketconnection - * @short_description: A socket connection - * @include: gio/gio.h - * @see_also: #GIOStream, #GSocketClient, #GSocketListener - * - * #GSocketConnection is a #GIOStream for a connected socket. They - * can be created either by #GSocketClient when connecting to a host, - * or by #GSocketListener when accepting a new client. - * - * The type of the #GSocketConnection object returned from these calls - * depends on the type of the underlying socket that is in use. For - * instance, for a TCP/IP connection it will be a #GTcpConnection. - * - * Choosing what type of object to construct is done with the socket - * connection factory, and it is possible for 3rd parties to register - * custom socket connection types for specific combination of socket - * family/type/protocol using g_socket_connection_factory_register_type(). - * - * To close a #GSocketConnection, use g_io_stream_close(). Closing both - * substreams of the #GIOStream separately will not close the underlying - * #GSocket. - * - * Since: 2.22 - */ - - -/** - * SECTION:gsocketcontrolmessage - * @title: GSocketControlMessage - * @short_description: A GSocket control message - * @include: gio/gio.h - * @see_also: #GSocket. - * - * A #GSocketControlMessage is a special-purpose utility message that - * can be sent to or received from a #GSocket. These types of - * messages are often called "ancillary data". - * - * The message can represent some sort of special instruction to or - * information from the socket or can represent a special kind of - * transfer to the peer (for example, sending a file descriptor over - * a UNIX socket). - * - * These messages are sent with g_socket_send_message() and received - * with g_socket_receive_message(). - * - * To extend the set of control message that can be sent, subclass this - * class and override the get_size, get_level, get_type and serialize - * methods. - * - * To extend the set of control messages that can be received, subclass - * this class and implement the deserialize method. Also, make sure your - * class is registered with the GType typesystem before calling - * g_socket_receive_message() to read such a message. - * - * Since: 2.22 - */ - - -/** - * SECTION:gsocketlistener - * @title: GSocketListener - * @short_description: Helper for accepting network client connections - * @include: gio/gio.h - * @see_also: #GThreadedSocketService, #GSocketService. - * - * A #GSocketListener is an object that keeps track of a set - * of server sockets and helps you accept sockets from any of the - * socket, either sync or async. - * - * Add addresses and ports to listen on using g_socket_listener_add_address() - * and g_socket_listener_add_inet_port(). These will be listened on until - * g_socket_listener_close() is called. Dropping your final reference to the - * #GSocketListener will not cause g_socket_listener_close() to be called - * implicitly, as some references to the #GSocketListener may be held - * internally. - * - * If you want to implement a network server, also look at #GSocketService - * and #GThreadedSocketService which are subclasses of #GSocketListener - * that make this even easier. - * - * Since: 2.22 - */ - - -/** - * SECTION:gsocketservice - * @title: GSocketService - * @short_description: Make it easy to implement a network service - * @include: gio/gio.h - * @see_also: #GThreadedSocketService, #GSocketListener. - * - * A #GSocketService is an object that represents a service that - * is provided to the network or over local sockets. When a new - * connection is made to the service the #GSocketService::incoming - * signal is emitted. - * - * A #GSocketService is a subclass of #GSocketListener and you need - * to add the addresses you want to accept connections on with the - * #GSocketListener APIs. - * - * There are two options for implementing a network service based on - * #GSocketService. The first is to create the service using - * g_socket_service_new() and to connect to the #GSocketService::incoming - * signal. The second is to subclass #GSocketService and override the - * default signal handler implementation. - * - * In either case, the handler must immediately return, or else it - * will block additional incoming connections from being serviced. - * If you are interested in writing connection handlers that contain - * blocking code then see #GThreadedSocketService. - * - * The socket service runs on the main loop of the - * [thread-default context][g-main-context-push-thread-default-context] - * of the thread it is created in, and is not - * threadsafe in general. However, the calls to start and stop the - * service are thread-safe so these can be used from threads that - * handle incoming clients. - * - * Since: 2.22 - */ - - -/** - * SECTION:gsrvtarget - * @short_description: DNS SRV record target - * @include: gio/gio.h - * - * SRV (service) records are used by some network protocols to provide - * service-specific aliasing and load-balancing. For example, XMPP - * (Jabber) uses SRV records to locate the XMPP server for a domain; - * rather than connecting directly to "example.com" or assuming a - * specific server hostname like "xmpp.example.com", an XMPP client - * would look up the "xmpp-client" SRV record for "example.com", and - * then connect to whatever host was pointed to by that record. - * - * You can use g_resolver_lookup_service() or - * g_resolver_lookup_service_async() to find the #GSrvTargets - * for a given service. However, if you are simply planning to connect - * to the remote service, you can use #GNetworkService's - * #GSocketConnectable interface and not need to worry about - * #GSrvTarget at all. - */ - - -/** - * SECTION:gsubprocess - * @title: GSubprocess - * @short_description: Child processes - * @include: gio/gio.h - * @see_also: #GSubprocessLauncher - * - * #GSubprocess allows the creation of and interaction with child - * processes. - * - * Processes can be communicated with using standard GIO-style APIs (ie: - * #GInputStream, #GOutputStream). There are GIO-style APIs to wait for - * process termination (ie: cancellable and with an asynchronous - * variant). - * - * There is an API to force a process to terminate, as well as a - * race-free API for sending UNIX signals to a subprocess. - * - * One major advantage that GIO brings over the core GLib library is - * comprehensive API for asynchronous I/O, such - * g_output_stream_splice_async(). This makes GSubprocess - * significantly more powerful and flexible than equivalent APIs in - * some other languages such as the `subprocess.py` - * included with Python. For example, using #GSubprocess one could - * create two child processes, reading standard output from the first, - * processing it, and writing to the input stream of the second, all - * without blocking the main loop. - * - * A powerful g_subprocess_communicate() API is provided similar to the - * `communicate()` method of `subprocess.py`. This enables very easy - * interaction with a subprocess that has been opened with pipes. - * - * #GSubprocess defaults to tight control over the file descriptors open - * in the child process, avoiding dangling-fd issues that are caused by - * a simple fork()/exec(). The only open file descriptors in the - * spawned process are ones that were explicitly specified by the - * #GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was - * specified). - * - * #GSubprocess will quickly reap all child processes as they exit, - * avoiding "zombie processes" remaining around for long periods of - * time. g_subprocess_wait() can be used to wait for this to happen, - * but it will happen even without the call being explicitly made. - * - * As a matter of principle, #GSubprocess has no API that accepts - * shell-style space-separated strings. It will, however, match the - * typical shell behaviour of searching the PATH for executables that do - * not contain a directory separator in their name. - * - * #GSubprocess attempts to have a very simple API for most uses (ie: - * spawning a subprocess with arguments and support for most typical - * kinds of input and output redirection). See g_subprocess_new(). The - * #GSubprocessLauncher API is provided for more complicated cases - * (advanced types of redirection, environment variable manipulation, - * change of working directory, child setup functions, etc). - * - * A typical use of #GSubprocess will involve calling - * g_subprocess_new(), followed by g_subprocess_wait_async() or - * g_subprocess_wait(). After the process exits, the status can be - * checked using functions such as g_subprocess_get_if_exited() (which - * are similar to the familiar WIFEXITED-style POSIX macros). - * - * Since: 2.40 - */ - - -/** - * SECTION:gsubprocesslauncher - * @title: GSubprocess Launcher - * @short_description: Environment options for launching a child process - * @include: gio/gio.h - * - * This class contains a set of options for launching child processes, - * such as where its standard input and output will be directed, the - * argument list, the environment, and more. - * - * While the #GSubprocess class has high level functions covering - * popular cases, use of this class allows access to more advanced - * options. It can also be used to launch multiple subprocesses with - * a similar configuration. - * - * Since: 2.40 - */ - - -/** - * SECTION:gtask - * @short_description: Cancellable synchronous or asynchronous task - * and result - * @include: gio/gio.h - * @see_also: #GAsyncResult - * - * A #GTask represents and manages a cancellable "task". - * - * ## Asynchronous operations - * - * 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 in the - * [thread-default main context][g-main-context-push-thread-default] - * where it was created (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. - * - * Here is an example for using GTask as a GAsyncResult: - * |[ - * 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 (task, 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); - * } - * ]| - * - * ## Chained asynchronous operations - * - * #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 [I/O priority][io-priority] - * 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). - * - * Here is an example for chained asynchronous operations: - * |[ - * 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 (task, g_object_ref (cake), g_object_unref); - * g_object_unref (task); - * } - * - * static gboolean - * 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); - * - * return G_SOURCE_REMOVE; - * } - * - * 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 (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, 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); - * } - * ]| - * - * ## Asynchronous operations from synchronous ones - * - * You can use g_task_run_in_thread() to turn a synchronous - * operation into an asynchronous one, by running it in a thread. - * When it completes, the result will be dispatched to the - * [thread-default main context][g-main-context-push-thread-default] - * where the #GTask was created. - * - * Running a task in a thread: - * |[ - * 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); - * g_object_unref (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); - * } - * ]| - * - * ## Adding cancellability to uncancellable tasks - * - * 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. - * - * Cancelling a task: - * |[ - * 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; - * } - * ]| - * - * ## Porting from GSimpleAsyncResult - * - * #GTask's API attempts to be simpler than #GSimpleAsyncResult's - * in several ways: - * - 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. - * - In addition to the task data, #GTask also keeps track of the - * [priority][io-priority], #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. - * - 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 - * `task_func`, even if the task's #GCancellable - * is already cancelled before the task gets a chance to run; - * you can start your `task_func` with a - * g_task_return_error_if_cancelled() check if you need the - * old behavior. - * - 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.) - * - 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. - * - With #GSimpleAsyncResult, it was common to call - * g_simple_async_result_propagate_error() from the - * `_finish()` 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 `g_task_propagate_` 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 `_async()` wrapper - * function (for "short-circuit" results, such as when passing - * 0 to g_input_stream_read_async()). - */ - - -/** - * SECTION:gtcpconnection - * @title: GTcpConnection - * @short_description: A TCP GSocketConnection - * @include: gio/gio.h - * @see_also: #GSocketConnection. - * - * This is the subclass of #GSocketConnection that is created - * for TCP/IP sockets. - * - * Since: 2.22 - */ - - -/** - * SECTION:gtcpwrapperconnection - * @title: GTcpWrapperConnection - * @short_description: Wrapper for non-GSocketConnection-based, - * GSocket-based GIOStreams - * @include: gio/gio.h - * @see_also: #GSocketConnection. - * - * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is - * based on a #GSocket, but which is not actually a - * #GSocketConnection. This is used by #GSocketClient so that it can - * always return a #GSocketConnection, even when the connection it has - * actually created is not directly a #GSocketConnection. - * - * Since: 2.28 - */ - - -/** - * SECTION:gtestdbus - * @short_description: D-Bus testing helper - * @include: gio/gio.h - * - * A helper class for testing code which uses D-Bus without touching the user's - * session bus. - * - * Note that #GTestDBus modifies the user’s environment, calling setenv(). - * This is not thread-safe, so all #GTestDBus calls should be completed before - * threads are spawned, or should have appropriate locking to ensure no access - * conflicts to environment variables shared between #GTestDBus and other - * threads. - * - * ## Creating unit tests using GTestDBus - * - * 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. - * - * 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. - * - * 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. - * |[ - * [D-BUS Service] - * Name=org.gtk.GDBus.Examples.ObjectManager - * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server - * ]| - * 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: - * |[ - * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" - * ]| - * Once you have a service definition file which is local to your source tree, - * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding. - * - * An example of a test fixture for D-Bus services can be found - * here: - * [gdbus-test-fixture.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-test-fixture.c) - * - * 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). - * - * 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. - * - * 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: - * |[ - * all-am: - * $(GLIB_COMPILE_SCHEMAS) . - * - * CLEANFILES += gschemas.compiled - * ]| - */ - - -/** - * SECTION:gthemedicon - * @short_description: Icon theming support - * @include: gio/gio.h - * @see_also: #GIcon, #GLoadableIcon - * - * #GThemedIcon is an implementation of #GIcon that supports icon themes. - * #GThemedIcon contains a list of all of the icons present in an icon - * theme, so that icons can be looked up quickly. #GThemedIcon does - * not provide actual pixmaps for icons, just the icon names. - * Ideally something like gtk_icon_theme_choose_icon() should be used to - * resolve the list of names so that fallback icons work nicely with - * themes that inherit other themes. - */ - - -/** - * SECTION:gthreadedsocketservice - * @title: GThreadedSocketService - * @short_description: A threaded GSocketService - * @include: gio/gio.h - * @see_also: #GSocketService. - * - * A #GThreadedSocketService is a simple subclass of #GSocketService - * that handles incoming connections by creating a worker thread and - * dispatching the connection to it by emitting the - * #GThreadedSocketService::run signal in the new thread. - * - * The signal handler may perform blocking IO and need not return - * until the connection is closed. - * - * The service is implemented using a thread pool, so there is a - * limited amount of threads available to serve incoming requests. - * The service automatically stops the #GSocketService from accepting - * new connections when all threads are busy. - * - * As with #GSocketService, you may connect to #GThreadedSocketService::run, - * or subclass and override the default handler. - */ - - -/** - * SECTION:gtls - * @title: TLS Overview - * @short_description: TLS (aka SSL) support for GSocketConnection - * @include: gio/gio.h - * - * #GTlsConnection and related classes provide TLS (Transport Layer - * Security, previously known as SSL, Secure Sockets Layer) support for - * gio-based network streams. - * - * #GDtlsConnection and related classes provide DTLS (Datagram TLS) support for - * GIO-based network sockets, using the #GDatagramBased interface. The TLS and - * DTLS APIs are almost identical, except TLS is stream-based and DTLS is - * datagram-based. They share certificate and backend infrastructure. - * - * In the simplest case, for a client TLS connection, you can just set the - * #GSocketClient:tls flag on a #GSocketClient, and then any - * connections created by that client will have TLS negotiated - * automatically, using appropriate default settings, and rejecting - * any invalid or self-signed certificates (unless you change that - * default by setting the #GSocketClient:tls-validation-flags - * property). The returned object will be a #GTcpWrapperConnection, - * which wraps the underlying #GTlsClientConnection. - * - * For greater control, you can create your own #GTlsClientConnection, - * wrapping a #GSocketConnection (or an arbitrary #GIOStream with - * pollable input and output streams) and then connect to its signals, - * such as #GTlsConnection::accept-certificate, before starting the - * handshake. - * - * Server-side TLS is similar, using #GTlsServerConnection. At the - * moment, there is no support for automatically wrapping server-side - * connections in the way #GSocketClient does for client-side - * connections. - */ - - -/** - * SECTION:gtlsbackend - * @title: GTlsBackend - * @short_description: TLS backend implementation - * @include: gio/gio.h - * - * TLS (Transport Layer Security, aka SSL) and DTLS backend. - * - * Since: 2.28 - */ - - -/** - * SECTION:gtlscertificate - * @title: GTlsCertificate - * @short_description: TLS certificate - * @include: gio/gio.h - * @see_also: #GTlsConnection - * - * A certificate used for TLS authentication and encryption. - * This can represent either a certificate only (eg, the certificate - * received by a client from a server), or the combination of - * a certificate and a private key (which is needed when acting as a - * #GTlsServerConnection). - * - * Since: 2.28 - */ - - -/** - * SECTION:gtlsclientconnection - * @short_description: TLS client-side connection - * @include: gio/gio.h - * - * #GTlsClientConnection is the client-side subclass of - * #GTlsConnection, representing a client-side TLS connection. - */ - - -/** - * SECTION:gtlsconnection - * @short_description: TLS connection type - * @include: gio/gio.h - * - * #GTlsConnection is the base TLS connection class type, which wraps - * a #GIOStream and provides TLS encryption on top of it. Its - * subclasses, #GTlsClientConnection and #GTlsServerConnection, - * implement client-side and server-side TLS, respectively. - * - * For DTLS (Datagram TLS) support, see #GDtlsConnection. - * - * Since: 2.28 - */ - - -/** - * SECTION:gtlsdatabase - * @short_description: TLS database type - * @include: gio/gio.h - * - * #GTlsDatabase is used to look up certificates and other information - * from a certificate or key store. It is an abstract base class which - * TLS library specific subtypes override. - * - * A #GTlsDatabase may be accessed from multiple threads by the TLS backend. - * All implementations are required to be fully thread-safe. - * - * Most common client applications will not directly interact with - * #GTlsDatabase. It is used internally by #GTlsConnection. - * - * Since: 2.30 - */ - - -/** - * SECTION:gtlsfiledatabase - * @short_description: TLS file based database type - * @include: gio/gio.h - * - * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load - * their certificate information from a file. It is an interface which - * TLS library specific subtypes implement. - * - * Since: 2.30 - */ - - -/** - * SECTION:gtlsinteraction - * @short_description: Interaction with the user during TLS operations. - * @include: gio/gio.h - * - * #GTlsInteraction provides a mechanism for the TLS connection and database - * code to interact with the user. It can be used to ask the user for passwords. - * - * To use a #GTlsInteraction with a TLS connection use - * g_tls_connection_set_interaction(). - * - * Callers should instantiate a derived class that implements the various - * interaction methods to show the required dialogs. - * - * Callers should use the 'invoke' functions like - * g_tls_interaction_invoke_ask_password() to run interaction methods. These - * functions make sure that the interaction is invoked in the main loop - * and not in the current thread, if the current thread is not running the - * main loop. - * - * Derived classes can choose to implement whichever interactions methods they'd - * like to support by overriding those virtual methods in their class - * initialization function. Any interactions not implemented will return - * %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method, - * it must also implement the corresponding finish method. - */ - - -/** - * SECTION:gtlspassword - * @title: GTlsPassword - * @short_description: TLS Passwords for prompting - * @include: gio/gio.h - * - * Holds a password used in TLS. - */ - - -/** - * SECTION:gtlsserverconnection - * @short_description: TLS server-side connection - * @include: gio/gio.h - * - * #GTlsServerConnection is the server-side subclass of #GTlsConnection, - * representing a server-side TLS connection. - * - * Since: 2.28 - */ - - -/** - * SECTION:gunixconnection - * @title: GUnixConnection - * @short_description: A UNIX domain GSocketConnection - * @include: gio/gunixconnection.h - * @see_also: #GSocketConnection. - * - * This is the subclass of #GSocketConnection that is created - * for UNIX domain sockets. - * - * It contains functions to do some of the UNIX socket specific - * functionality like passing file descriptors. - * - * Note that `` belongs to the UNIX-specific - * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` - * pkg-config file when using it. - * - * Since: 2.22 - */ - - -/** - * SECTION:gunixcredentialsmessage - * @title: GUnixCredentialsMessage - * @short_description: A GSocketControlMessage containing credentials - * @include: gio/gunixcredentialsmessage.h - * @see_also: #GUnixConnection, #GSocketControlMessage - * - * This #GSocketControlMessage contains a #GCredentials instance. It - * may be sent using g_socket_send_message() and received using - * g_socket_receive_message() over UNIX sockets (ie: sockets in the - * %G_SOCKET_FAMILY_UNIX family). - * - * For an easier way to send and receive credentials over - * stream-oriented UNIX sockets, see - * g_unix_connection_send_credentials() and - * g_unix_connection_receive_credentials(). To receive credentials of - * a foreign process connected to a socket, use - * g_socket_get_credentials(). - */ - - -/** - * SECTION:gunixfdlist - * @title: GUnixFDList - * @short_description: An object containing a set of UNIX file descriptors - * @include: gio/gunixfdlist.h - * @see_also: #GUnixFDMessage - * - * A #GUnixFDList contains a list of file descriptors. It owns the file - * descriptors that it contains, closing them when finalized. - * - * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in - * the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message() - * and received using g_socket_receive_message(). - * - * Note that `` belongs to the UNIX-specific GIO - * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config - * file when using it. - */ - - -/** - * SECTION:gunixfdmessage - * @title: GUnixFDMessage - * @short_description: A GSocketControlMessage containing a GUnixFDList - * @include: gio/gunixfdmessage.h - * @see_also: #GUnixConnection, #GUnixFDList, #GSocketControlMessage - * - * This #GSocketControlMessage contains a #GUnixFDList. - * It may be sent using g_socket_send_message() and received using - * g_socket_receive_message() over UNIX sockets (ie: sockets in the - * %G_SOCKET_FAMILY_UNIX family). The file descriptors are copied - * between processes by the kernel. - * - * For an easier way to send and receive file descriptors over - * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and - * g_unix_connection_receive_fd(). - * - * Note that `` belongs to the UNIX-specific GIO - * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config - * file when using it. - */ - - -/** - * SECTION:gunixinputstream - * @short_description: Streaming input operations for UNIX file descriptors - * @include: gio/gunixinputstream.h - * @see_also: #GInputStream - * - * #GUnixInputStream implements #GInputStream for reading from a UNIX - * file descriptor, including asynchronous operations. (If the file - * descriptor refers to a socket or pipe, this will use poll() to do - * asynchronous I/O. If it refers to a regular file, it will fall back - * to doing asynchronous I/O in another thread.) - * - * Note that `` belongs to the UNIX-specific GIO - * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config - * file when using it. - */ - - -/** - * SECTION:gunixmounts - * @include: gio/gunixmounts.h - * @short_description: UNIX mounts - * - * Routines for managing mounted UNIX mount points and paths. - * - * Note that `` belongs to the UNIX-specific GIO - * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config - * file when using it. - */ - - -/** - * SECTION:gunixoutputstream - * @short_description: Streaming output operations for UNIX file descriptors - * @include: gio/gunixoutputstream.h - * @see_also: #GOutputStream - * - * #GUnixOutputStream implements #GOutputStream for writing to a UNIX - * file descriptor, including asynchronous operations. (If the file - * descriptor refers to a socket or pipe, this will use poll() to do - * asynchronous I/O. If it refers to a regular file, it will fall back - * to doing asynchronous I/O in another thread.) - * - * Note that `` belongs to the UNIX-specific GIO - * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file - * when using it. - */ - - -/** - * SECTION:gunixsocketaddress - * @short_description: UNIX GSocketAddress - * @include: gio/gunixsocketaddress.h - * - * Support for UNIX-domain (also known as local) sockets. - * - * UNIX domain sockets are generally visible in the filesystem. - * However, some systems support abstract socket names which are not - * visible in the filesystem and not affected by the filesystem - * permissions, visibility, etc. Currently this is only supported - * under Linux. If you attempt to use abstract sockets on other - * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED - * errors. You can use g_unix_socket_address_abstract_names_supported() - * to see if abstract names are supported. - * - * Note that `` belongs to the UNIX-specific GIO - * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file - * when using it. - */ - - -/** - * SECTION:gvfs - * @short_description: Virtual File System - * @include: gio/gio.h - * - * Entry point for using GIO functionality. - */ - - -/** - * SECTION:gvolume - * @short_description: Volume management - * @include: gio/gio.h - * - * The #GVolume interface represents user-visible objects that can be - * mounted. Note, when porting from GnomeVFS, #GVolume is the moral - * equivalent of #GnomeVFSDrive. - * - * Mounting a #GVolume instance is an asynchronous operation. For more - * information about asynchronous operations, see #GAsyncResult and - * #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 - * starts since it's not desirable to put up a lot of dialogs asking - * for credentials. - * - * The callback will be fired when the operation has resolved (either - * with success or failure), and a #GAsyncResult instance will be - * passed to the callback. That callback should then call - * g_volume_mount_finish() with the #GVolume instance and the - * #GAsyncResult data to see if the operation was completed - * successfully. If an @error is present when g_volume_mount_finish() - * is called, then it will be filled with any error information. - * - * ## Volume Identifiers # {#volume-identifier} - * - * It is sometimes necessary to directly access the underlying - * operating system object behind a volume (e.g. for passing a volume - * to an application via the commandline). For this purpose, GIO - * allows to obtain an 'identifier' for the volume. There can be - * different kinds of identifiers, such as Hal UDIs, filesystem labels, - * traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined - * strings as names for the different kinds of identifiers: - * #G_VOLUME_IDENTIFIER_KIND_UUID, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. - * Use g_volume_get_identifier() to obtain an identifier for a volume. - * - * - * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available - * when the gvfs hal volume monitor is in use. Other volume monitors - * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE - * identifier, which can be used to obtain a hal device by means of - * libhal_manager_find_device_string_match(). - */ - - -/** - * SECTION:gvolumemonitor - * @short_description: Volume Monitor - * @include: gio/gio.h - * @see_also: #GFileMonitor - * - * #GVolumeMonitor is for listing the user interesting devices and volumes - * on the computer. In other words, what a file selector or file manager - * would show in a sidebar. - * - * #GVolumeMonitor is not - * [thread-default-context aware][g-main-context-push-thread-default], - * and so should not be used other than from the main thread, with no - * thread-default-context active. - * - * In order to receive updates about volumes and mounts monitored through GVFS, - * a main loop must be running. - */ - - -/** - * SECTION:gwin32inputstream - * @short_description: Streaming input operations for Windows file handles - * @include: gio/gwin32inputstream.h - * @see_also: #GInputStream - * - * #GWin32InputStream implements #GInputStream for reading from a - * Windows file handle. - * - * Note that `` belongs to the Windows-specific GIO - * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file - * when using it. - */ - - -/** - * SECTION:gwin32outputstream - * @short_description: Streaming output operations for Windows file handles - * @include: gio/gwin32outputstream.h - * @see_also: #GOutputStream - * - * #GWin32OutputStream implements #GOutputStream for writing to a - * Windows file handle. - * - * Note that `` belongs to the Windows-specific GIO - * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file - * when using it. - */ - - -/** - * SECTION:gwin32registrykey - * @title: GWin32RegistryKey - * @short_description: W32 registry access helper - * @include: gio/win32/gwin32registrykey.h - * - * #GWin32RegistryKey represents a single Windows Registry key. - * - * #GWin32RegistryKey is used by a number of helper functions that read - * Windows Registry. All keys are opened with read-only access, and at - * the moment there is no API for writing into registry keys or creating - * new ones. - * - * #GWin32RegistryKey implements the #GInitable interface, so if it is manually - * constructed by e.g. g_object_new() you must call g_initable_init() and check - * the results before using the object. This is done automatically - * in g_win32_registry_key_new() and g_win32_registry_key_get_child(), so these - * functions can return %NULL. - * - * To increase efficiency, a UTF-16 variant is available for all functions - * that deal with key or value names in the registry. Use these to perform - * deep registry queries or other operations that require querying a name - * of a key or a value and then opening it (or querying its data). The use - * of UTF-16 functions avoids the overhead of converting names to UTF-8 and - * back. - * - * All functions operate in current user's context (it is not possible to - * access registry tree of a different user). - * - * Key paths must use '\\' as a separator, '/' is not supported. Key names - * must not include '\\', because it's used as a separator. Value names - * can include '\\'. - * - * Key and value names are not case sensitive. - * - * Full key name (excluding the pre-defined ancestor's name) can't exceed - * 255 UTF-16 characters, give or take. Value name can't exceed 16383 UTF-16 - * characters. Tree depth is limited to 512 levels. - */ - - -/** - * SECTION:gzlibcompressor - * @short_description: Zlib compressor - * @include: gio/gio.h - * - * #GZlibCompressor is an implementation of #GConverter that - * compresses data using zlib. - */ - - -/** - * SECTION:gzlibdecompressor - * @short_description: Zlib decompressor - * @include: gio/gio.h - * - * #GZlibDecompressor is an implementation of #GConverter that - * decompresses data compressed with zlib. - */ - - -/** - * _g_dbus_initialize: - * - * Does various one-time init things such as - * - * - registering the G_DBUS_ERROR error domain - * - parses the G_DBUS_DEBUG environment variable - */ - - -/** - * _g_file_attribute_value_as_string: - * @attr: a #GFileAttributeValue. - * - * Converts a #GFileAttributeValue to a string for display. - * The returned string should be freed when no longer needed. - * - * Returns: a string from the @attr, %NULL on error, or "" - * if @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID. - */ - - -/** - * _g_file_attribute_value_clear: - * @attr: a #GFileAttributeValue. - * - * Clears the value of @attr and sets its type to - * %G_FILE_ATTRIBUTE_TYPE_INVALID. - */ - - -/** - * _g_file_attribute_value_free: - * @attr: a #GFileAttributeValue. - * - * Frees the memory used by @attr. - */ - - -/** - * _g_file_attribute_value_get_boolean: - * @attr: a #GFileAttributeValue. - * - * Gets the boolean value from a file attribute value. If the value is not the - * right type then %FALSE will be returned. - * - * Returns: the boolean value contained within the attribute, or %FALSE. - */ - - -/** - * _g_file_attribute_value_get_byte_string: - * @attr: a #GFileAttributeValue. - * - * Gets the byte string from a file attribute value. If the value is not the - * right type then %NULL will be returned. - * - * Returns: the byte string contained within the attribute or %NULL. - */ - - -/** - * _g_file_attribute_value_get_int32: - * @attr: a #GFileAttributeValue. - * - * Gets the signed 32-bit integer from a file attribute value. If the value - * is not the right type then 0 will be returned. - * - * Returns: the signed 32-bit integer from the attribute, or 0. - */ - - -/** - * _g_file_attribute_value_get_int64: - * @attr: a #GFileAttributeValue. - * - * Gets the signed 64-bit integer from a file attribute value. If the value - * is not the right type then 0 will be returned. - * - * Returns: the signed 64-bit integer from the attribute, or 0. - */ - - -/** - * _g_file_attribute_value_get_object: - * @attr: a #GFileAttributeValue. - * - * Gets the GObject from a file attribute value. If the value - * is not the right type then %NULL will be returned. - * - * Returns: the GObject from the attribute, or %NULL. - */ - - -/** - * _g_file_attribute_value_get_string: - * @attr: a #GFileAttributeValue. - * - * Gets the string from a file attribute value. If the value is not the - * right type then %NULL will be returned. - * - * Returns: the UTF-8 string value contained within the attribute, or %NULL. - */ - - -/** - * _g_file_attribute_value_get_uint32: - * @attr: a #GFileAttributeValue. - * - * Gets the unsigned 32-bit integer from a file attribute value. If the value - * is not the right type then 0 will be returned. - * - * Returns: the unsigned 32-bit integer from the attribute, or 0. - */ - - -/** - * _g_file_attribute_value_get_uint64: - * @attr: a #GFileAttributeValue. - * - * Gets the unsigned 64-bit integer from a file attribute value. If the value - * is not the right type then 0 will be returned. - * - * Returns: the unsigned 64-bit integer from the attribute, or 0. - */ - - -/** - * _g_file_attribute_value_new: - * - * Creates a new file attribute. - * - * Returns: a #GFileAttributeValue. - */ - - -/** - * _g_file_attribute_value_set_boolean: - * @attr: a #GFileAttributeValue. - * @value: a #gboolean to set within the type. - * - * Sets the attribute value to the given boolean value. - */ - - -/** - * _g_file_attribute_value_set_byte_string: - * @attr: a #GFileAttributeValue. - * @string: a byte string to set within the type. - * - * Sets the attribute value to a given byte string. - */ - - -/** - * _g_file_attribute_value_set_int32: - * @attr: a #GFileAttributeValue. - * @value: a #gint32 to set within the type. - * - * Sets the attribute value to the given signed 32-bit integer. - */ - - -/** - * _g_file_attribute_value_set_int64: - * @attr: a #GFileAttributeValue. - * @value: a #gint64 to set within the type. - * - * Sets the attribute value to a given signed 64-bit integer. - */ - - -/** - * _g_file_attribute_value_set_object: - * @attr: a #GFileAttributeValue. - * @obj: a #GObject. - * - * Sets the attribute to contain the value @obj. - * The @attr references the GObject internally. - */ - - -/** - * _g_file_attribute_value_set_string: - * @attr: a #GFileAttributeValue. - * @string: a UTF-8 string to set within the type. - * - * Sets the attribute value to a given UTF-8 string. - */ - - -/** - * _g_file_attribute_value_set_uint32: - * @attr: a #GFileAttributeValue. - * @value: a #guint32 to set within the type. - * - * Sets the attribute value to the given unsigned 32-bit integer. - */ - - -/** - * _g_file_attribute_value_set_uint64: - * @attr: a #GFileAttributeValue. - * @value: a #guint64 to set within the type. - * - * Sets the attribute value to a given unsigned 64-bit integer. - */ - - -/** - * _g_io_module_extract_name: - * @filename: filename of a GIOModule - * - * Extract the plugin name from its filename. It removes optional "lib" or - * "libgio" prefix, and removes everything after the first dot. For example: - * "libgiognutls.so" -> "gnutls". - * - * Returns: (transfer full): the module's name - */ - - -/** - * _g_io_module_get_default: - * @extension_point: the name of an extension point - * @envvar: (nullable): the name of an environment variable to - * override the default implementation. - * @verify_func: (nullable): a function to call to verify that - * a given implementation is usable in the current environment. - * - * Retrieves the default object 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 an extension point implementation implements #GInitable, then - * that implementation will only be used if it initializes - * successfully. Otherwise, if @verify_func is not %NULL, then it will - * be called on each candidate implementation after construction, to - * check if it is actually usable or not. - * - * The result is cached after it is generated the first time (but the cache does - * not keep a strong reference to the object), and - * the function is thread-safe. - * - * Returns: (transfer full) (nullable): an object implementing - * @extension_point, or %NULL if there are no usable - * implementations. - */ - - -/** - * _g_io_module_get_default_type: - * @extension_point: the name of an extension point - * @envvar: (nullable): 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): the type to instantiate to implement - * @extension_point, or %G_TYPE_INVALID if there are no usable - * implementations. - */ - - -/** - * _g_poll_file_monitor_new: - * @file: a #GFile. - * - * Polls @file for changes. - * - * Returns: a new #GFileMonitor for the given #GFile. - */ - - -/** - * g_action_activate: - * @action: a #GAction - * @parameter: (nullable): the parameter to the activation - * - * Activates the action. - * - * @parameter must be the correct type of parameter for the action (ie: - * 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 - */ - - -/** - * g_action_change_state: - * @action: a #GAction - * @value: the new state - * - * Request for the state of @action to be changed to @value. - * - * The action must be stateful and @value must be of the correct type. - * See g_action_get_state_type(). - * - * This call merely requests a change. The action may refuse to change - * its state or may change its state to something other than @value. - * See g_action_get_state_hint(). - * - * If the @value GVariant is floating, it is consumed. - * - * Since: 2.30 - */ - - -/** - * g_action_get_enabled: - * @action: a #GAction - * - * Checks if @action is currently enabled. - * - * An action must be enabled in order to be activated or in order to - * have its state changed from outside callers. - * - * Returns: whether the action is enabled - * Since: 2.28 - */ - - -/** - * g_action_get_name: - * @action: a #GAction - * - * Queries the name of @action. - * - * Returns: the name of the action - * Since: 2.28 - */ - - -/** - * g_action_get_parameter_type: - * @action: a #GAction - * - * Queries the type of the parameter that must be given when activating - * @action. - * - * When activating the action using g_action_activate(), the #GVariant - * given to that function must be of the type returned by this function. - * - * In the case that this function returns %NULL, you must not give any - * #GVariant, but %NULL instead. - * - * Returns: (nullable): the parameter type - * Since: 2.28 - */ - - -/** - * g_action_get_state: - * @action: a #GAction - * - * Queries the current state of @action. - * - * If the action is not stateful then %NULL will be returned. If the - * action is stateful then the type of the return value is the type - * given by g_action_get_state_type(). - * - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. - * - * Returns: (nullable) (transfer full): the current state of the action - * Since: 2.28 - */ - - -/** - * g_action_get_state_hint: - * @action: a #GAction - * - * Requests a hint about the valid range of values for the state of - * @action. - * - * If %NULL is returned it either means that the action is not stateful - * or that there is no hint about the valid range of values for the - * state of the action. - * - * If a #GVariant array is returned then each item in the array is a - * possible value for the state. If a #GVariant pair (ie: two-tuple) is - * returned then the tuple specifies the inclusive lower and upper bound - * of valid values for the state. - * - * In any case, the information is merely a hint. It may be possible to - * have a state value outside of the hinted range and setting a value - * within the range may fail. - * - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. - * - * Returns: (nullable) (transfer full): the state range hint - * Since: 2.28 - */ - - -/** - * g_action_get_state_type: - * @action: a #GAction - * - * Queries the type of the state of @action. - * - * If the action is stateful (e.g. created with - * g_simple_action_new_stateful()) then this function returns the - * #GVariantType of the state. This is the type of the initial value - * given as the state. All calls to g_action_change_state() must give a - * #GVariant of this type and g_action_get_state() will return a - * #GVariant of the same type. - * - * If the action is not stateful (e.g. created with g_simple_action_new()) - * then this function will return %NULL. In that case, g_action_get_state() - * will return %NULL and you must not call g_action_change_state(). - * - * Returns: (nullable): the state type, if the action is stateful - * Since: 2.28 - */ - - -/** - * g_action_group_action_added: - * @action_group: a #GActionGroup - * @action_name: the name of an action in the group - * - * Emits the #GActionGroup::action-added signal on @action_group. - * - * This function should only be called by #GActionGroup implementations. - * - * Since: 2.28 - */ - - -/** - * g_action_group_action_enabled_changed: - * @action_group: a #GActionGroup - * @action_name: the name of an action in the group - * @enabled: whether or not the action is now enabled - * - * Emits the #GActionGroup::action-enabled-changed signal on @action_group. - * - * This function should only be called by #GActionGroup implementations. - * - * Since: 2.28 - */ - - -/** - * g_action_group_action_removed: - * @action_group: a #GActionGroup - * @action_name: the name of an action in the group - * - * Emits the #GActionGroup::action-removed signal on @action_group. - * - * This function should only be called by #GActionGroup implementations. - * - * Since: 2.28 - */ - - -/** - * g_action_group_action_state_changed: - * @action_group: a #GActionGroup - * @action_name: the name of an action in the group - * @state: the new state of the named action - * - * Emits the #GActionGroup::action-state-changed signal on @action_group. - * - * This function should only be called by #GActionGroup implementations. - * - * Since: 2.28 - */ - - -/** - * g_action_group_activate_action: - * @action_group: a #GActionGroup - * @action_name: the name of the action to activate - * @parameter: (nullable): parameters to the activation - * - * Activate the named action within @action_group. - * - * If the action is expecting a parameter, then the correct type of - * parameter must be given as @parameter. If the action is expecting no - * parameters then @parameter must be %NULL. See - * g_action_group_get_action_parameter_type(). - * - * If the #GActionGroup implementation supports asynchronous remote - * activation over D-Bus, this call may return before the relevant - * D-Bus traffic has been sent, or any replies have been received. In - * order to block on such asynchronous activation calls, - * g_dbus_connection_flush() should be called prior to the code, which - * depends on the result of the action activation. Without flushing - * the D-Bus connection, there is no guarantee that the action would - * have been activated. - * - * The following code which runs in a remote app instance, shows an - * example of a "quit" action being activated on the primary app - * instance over D-Bus. Here g_dbus_connection_flush() is called - * before `exit()`. Without g_dbus_connection_flush(), the "quit" action - * may fail to be activated on the primary instance. - * - * |[ - * // call "quit" action on primary instance - * g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); - * - * // make sure the action is activated now - * g_dbus_connection_flush (...); - * - * g_debug ("application has been terminated. exiting."); - * - * exit (0); - * ]| - * - * Since: 2.28 - */ - - -/** - * g_action_group_change_action_state: - * @action_group: a #GActionGroup - * @action_name: the name of the action to request the change on - * @value: the new state - * - * Request for the state of the named action within @action_group to be - * changed to @value. - * - * The action must be stateful and @value must be of the correct type. - * See g_action_group_get_action_state_type(). - * - * This call merely requests a change. The action may refuse to change - * its state or may change its state to something other than @value. - * See g_action_group_get_action_state_hint(). - * - * If the @value GVariant is floating, it is consumed. - * - * Since: 2.28 - */ - - -/** - * g_action_group_get_action_enabled: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query - * - * Checks if the named action within @action_group is currently enabled. - * - * An action must be enabled in order to be activated or in order to - * have its state changed from outside callers. - * - * Returns: whether or not the action is currently enabled - * Since: 2.28 - */ - - -/** - * g_action_group_get_action_parameter_type: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query - * - * Queries the type of the parameter that must be given when activating - * the named action within @action_group. - * - * When activating the action using g_action_group_activate_action(), - * the #GVariant given to that function must be of the type returned - * by this function. - * - * In the case that this function returns %NULL, you must not give any - * #GVariant, but %NULL instead. - * - * The parameter type of a particular action will never change but it is - * possible for an action to be removed and for a new action to be added - * with the same name but a different parameter type. - * - * Returns: (nullable): the parameter type - * Since: 2.28 - */ - - -/** - * g_action_group_get_action_state: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query - * - * Queries the current state of the named action within @action_group. - * - * If the action is not stateful then %NULL will be returned. If the - * action is stateful then the type of the return value is the type - * given by g_action_group_get_action_state_type(). - * - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. - * - * Returns: (nullable) (transfer full): the current state of the action - * Since: 2.28 - */ - - -/** - * g_action_group_get_action_state_hint: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query - * - * Requests a hint about the valid range of values for the state of the - * named action within @action_group. - * - * If %NULL is returned it either means that the action is not stateful - * or that there is no hint about the valid range of values for the - * state of the action. - * - * If a #GVariant array is returned then each item in the array is a - * possible value for the state. If a #GVariant pair (ie: two-tuple) is - * returned then the tuple specifies the inclusive lower and upper bound - * of valid values for the state. - * - * In any case, the information is merely a hint. It may be possible to - * have a state value outside of the hinted range and setting a value - * within the range may fail. - * - * The return value (if non-%NULL) should be freed with - * g_variant_unref() when it is no longer required. - * - * Returns: (nullable) (transfer full): the state range hint - * Since: 2.28 - */ - - -/** - * g_action_group_get_action_state_type: - * @action_group: a #GActionGroup - * @action_name: the name of the action to query - * - * Queries the type of the state of the named action within - * @action_group. - * - * If the action is stateful then this function returns the - * #GVariantType of the state. All calls to - * g_action_group_change_action_state() must give a #GVariant of this - * type and g_action_group_get_action_state() will return a #GVariant - * of the same type. - * - * If the action is not stateful then this function will return %NULL. - * In that case, g_action_group_get_action_state() will return %NULL - * and you must not call g_action_group_change_action_state(). - * - * The state type of a particular action will never change but it is - * possible for an action to be removed and for a new action to be added - * with the same name but a different state type. - * - * Returns: (nullable): the state type, if the action is stateful - * Since: 2.28 - */ - - -/** - * g_action_group_has_action: - * @action_group: a #GActionGroup - * @action_name: the name of the action to check for - * - * Checks if the named action exists within @action_group. - * - * Returns: whether the named action exists - * Since: 2.28 - */ - - -/** - * g_action_group_list_actions: - * @action_group: a #GActionGroup - * - * Lists the actions contained within @action_group. - * - * The caller is responsible for freeing the list with g_strfreev() when - * it is no longer required. - * - * Returns: (transfer full): a %NULL-terminated array of the names of the - * actions in the group - * Since: 2.28 - */ - - -/** - * g_action_group_query_action: - * @action_group: a #GActionGroup - * @action_name: the name of an action in the group - * @enabled: (out): if the action is presently enabled - * @parameter_type: (out) (optional): the parameter type, or %NULL if none needed - * @state_type: (out) (optional): the state type, or %NULL if stateless - * @state_hint: (out) (optional): the state hint, or %NULL if none - * @state: (out) (optional): the current state, or %NULL if stateless - * - * Queries all aspects of the named action within an @action_group. - * - * This function acquires the information available from - * g_action_group_has_action(), g_action_group_get_action_enabled(), - * g_action_group_get_action_parameter_type(), - * g_action_group_get_action_state_type(), - * g_action_group_get_action_state_hint() and - * g_action_group_get_action_state() with a single function call. - * - * This provides two main benefits. - * - * The first is the improvement in efficiency that comes with not having - * to perform repeated lookups of the action in order to discover - * different things about it. The second is that implementing - * #GActionGroup can now be done by only overriding this one virtual - * function. - * - * The interface provides a default implementation of this function that - * calls the individual functions, as required, to fetch the - * information. The interface also provides default implementations of - * those functions that call this function. All implementations, - * therefore, must override either this function or all of the others. - * - * If the action exists, %TRUE is returned and any of the requested - * fields (as indicated by having a non-%NULL reference passed in) are - * filled. If the action doesn't exist, %FALSE is returned and the - * fields may or may not have been modified. - * - * Returns: %TRUE if the action exists, else %FALSE - * Since: 2.32 - */ - - -/** - * g_action_map_add_action: - * @action_map: a #GActionMap - * @action: a #GAction - * - * Adds an action to the @action_map. - * - * If the action map already contains an action with the same name - * as @action then the old action is dropped from the action map. - * - * The action map takes its own reference on @action. - * - * Since: 2.32 - */ - - -/** - * g_action_map_add_action_entries: - * @action_map: a #GActionMap - * @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 - * - * A convenience function for creating multiple #GSimpleAction instances - * and adding them to a #GActionMap. - * - * Each action is constructed as per one #GActionEntry. - * - * |[ - * static void - * activate_quit (GSimpleAction *simple, - * GVariant *parameter, - * gpointer user_data) - * { - * exit (0); - * } - * - * static void - * activate_print_string (GSimpleAction *simple, - * GVariant *parameter, - * gpointer user_data) - * { - * g_print ("%s\n", g_variant_get_string (parameter, NULL)); - * } - * - * static GActionGroup * - * create_action_group (void) - * { - * const GActionEntry entries[] = { - * { "quit", activate_quit }, - * { "print-string", activate_print_string, "s" } - * }; - * GSimpleActionGroup *group; - * - * group = g_simple_action_group_new (); - * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL); - * - * return G_ACTION_GROUP (group); - * } - * ]| - * - * Since: 2.32 - */ - - -/** - * g_action_map_lookup_action: - * @action_map: a #GActionMap - * @action_name: the name of an action - * - * Looks up the action with the name @action_name in @action_map. - * - * If no such action exists, returns %NULL. - * - * Returns: (nullable) (transfer none): a #GAction, or %NULL - * Since: 2.32 - */ - - -/** - * g_action_map_remove_action: - * @action_map: a #GActionMap - * @action_name: the name of the action - * - * Removes the named action from the action map. - * - * If no action of this name is in the map then nothing happens. - * - * Since: 2.32 - */ - - -/** - * g_action_name_is_valid: - * @action_name: a 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: (nullable): 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_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. - * @error: a #GError. - * - * Adds a content type to the application information to indicate the - * application is capable of opening files with the given content type. - * - * Returns: %TRUE on success, %FALSE on error. - */ - - -/** - * g_app_info_can_delete: - * @appinfo: a #GAppInfo - * - * Obtains the information whether the #GAppInfo can be deleted. - * See g_app_info_delete(). - * - * Returns: %TRUE if @appinfo can be deleted - * Since: 2.20 - */ - - -/** - * g_app_info_can_remove_supports_type: - * @appinfo: a #GAppInfo. - * - * Checks if a supported content type can be removed from an application. - * - * Returns: %TRUE if it is possible to remove supported - * content types from a given @appinfo, %FALSE if not. - */ - - -/** - * g_app_info_create_from_commandline: - * @commandline: (type filename): the commandline to use - * @application_name: (nullable): the application name, or %NULL to use @commandline - * @flags: flags that can specify details of the created #GAppInfo - * @error: a #GError location to store the error occurring, %NULL to ignore. - * - * Creates a new #GAppInfo from the given information. - * - * Note that for @commandline, the quoting rules of the Exec key of the - * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) - * are applied. For example, if the @commandline contains - * percent-encoded URIs, the percent-character must be doubled in order to prevent it from - * being swallowed by Exec key unquoting. See the specification for exact quoting rules. - * - * Returns: (transfer full): new #GAppInfo for given command. - */ - - -/** - * g_app_info_delete: (virtual do_delete) - * @appinfo: a #GAppInfo - * - * Tries to delete a #GAppInfo. - * - * On some platforms, there may be a difference between user-defined - * #GAppInfos which can be deleted, and system-wide ones which cannot. - * See g_app_info_can_delete(). - * - * Returns: %TRUE if @appinfo has been deleted - * Since: 2.20 - */ - - -/** - * g_app_info_dup: - * @appinfo: a #GAppInfo. - * - * Creates a duplicate of a #GAppInfo. - * - * Returns: (transfer full): a duplicate of @appinfo. - */ - - -/** - * g_app_info_equal: - * @appinfo1: the first #GAppInfo. - * @appinfo2: the second #GAppInfo. - * - * Checks if two #GAppInfos are equal. - * - * Note that the check *may not* compare each individual - * field, and only does an identity check. In case detecting changes in the - * contents is needed, program code must additionally compare relevant fields. - * - * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. - */ - - -/** - * g_app_info_get_all: - * - * Gets a list of all of the applications currently registered - * on this system. - * - * For desktop files, this includes applications that have - * `NoDisplay=true` set or are excluded from display by means - * of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show(). - * The returned list does not include applications which have - * the `Hidden` key set. - * - * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos. - */ - - -/** - * g_app_info_get_all_for_type: - * @content_type: the content type to find a #GAppInfo for - * - * Gets a list of all #GAppInfos for a given content type, - * including the recommended and fallback #GAppInfos. See - * g_app_info_get_recommended_for_type() and - * g_app_info_get_fallback_for_type(). - * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos - * for given @content_type or %NULL on error. - */ - - -/** - * g_app_info_get_commandline: (virtual get_commandline) - * @appinfo: a #GAppInfo - * - * Gets the commandline with which the application will be - * started. - * - * Returns: (nullable) (type filename): a string containing the @appinfo's commandline, - * or %NULL if this information is not available - * Since: 2.20 - */ - - -/** - * g_app_info_get_default_for_type: - * @content_type: the content type to find a #GAppInfo for - * @must_support_uris: if %TRUE, the #GAppInfo is expected to - * support URIs - * - * Gets the default #GAppInfo for a given content type. - * - * Returns: (transfer full) (nullable): #GAppInfo for given @content_type or - * %NULL on error. - */ - - -/** - * g_app_info_get_default_for_uri_scheme: - * @uri_scheme: a string containing a URI scheme. - * - * Gets the default application for handling URIs with - * the given URI scheme. A URI scheme is the initial part - * of the URI, up to but not including the ':', e.g. "http", - * "ftp" or "sip". - * - * Returns: (transfer full) (nullable): #GAppInfo for given @uri_scheme or - * %NULL on error. - */ - - -/** - * g_app_info_get_description: - * @appinfo: a #GAppInfo. - * - * Gets a human-readable description of an installed application. - * - * Returns: (nullable): a string containing a description of the - * application @appinfo, or %NULL if none. - */ - - -/** - * g_app_info_get_display_name: - * @appinfo: a #GAppInfo. - * - * Gets the display name of the application. The display name is often more - * descriptive to the user than the name itself. - * - * Returns: the display name of the application for @appinfo, or the name if - * no display name is available. - * Since: 2.24 - */ - - -/** - * g_app_info_get_executable: (virtual get_executable) - * @appinfo: a #GAppInfo - * - * Gets the executable's name for the installed application. - * - * Returns: (type filename): a string containing the @appinfo's application - * binaries name - */ - - -/** - * g_app_info_get_fallback_for_type: - * @content_type: the content type to find a #GAppInfo for - * - * Gets a list of fallback #GAppInfos for a given content type, i.e. - * those applications which claim to support the given content type - * by MIME type subclassing and not directly. - * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos - * for given @content_type or %NULL on error. - * Since: 2.28 - */ - - -/** - * g_app_info_get_icon: - * @appinfo: a #GAppInfo. - * - * Gets the icon for the application. - * - * Returns: (nullable) (transfer none): the default #GIcon for @appinfo or %NULL - * if there is no default icon. - */ - - -/** - * g_app_info_get_id: - * @appinfo: a #GAppInfo. - * - * Gets the ID of an application. An id is a string that - * identifies the application. The exact format of the id is - * platform dependent. For instance, on Unix this is the - * desktop file id from the xdg menu specification. - * - * Note that the returned ID may be %NULL, depending on how - * the @appinfo has been constructed. - * - * Returns: (nullable): a string containing the application's ID. - */ - - -/** - * g_app_info_get_name: - * @appinfo: a #GAppInfo. - * - * Gets the installed name of the application. - * - * Returns: the name of the application for @appinfo. - */ - - -/** - * g_app_info_get_recommended_for_type: - * @content_type: the content type to find a #GAppInfo for - * - * Gets a list of recommended #GAppInfos for a given content type, i.e. - * those applications which claim to support the given content type exactly, - * and not by MIME type subclassing. - * Note that the first application of the list is the last used one, i.e. - * the last one for which g_app_info_set_as_last_used_for_type() has been - * called. - * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos - * for given @content_type or %NULL on error. - * Since: 2.28 - */ - - -/** - * g_app_info_get_supported_types: - * @appinfo: a #GAppInfo that can handle files - * - * Retrieves the list of content types that @app_info claims to support. - * If this information is not provided by the environment, this function - * will return %NULL. - * This function does not take in consideration associations added with - * g_app_info_add_supports_type(), but only those exported directly by - * the application. - * - * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): - * a list of content types. - * Since: 2.34 - */ - - -/** - * g_app_info_launch: - * @appinfo: a #GAppInfo - * @files: (nullable) (element-type GFile): a #GList of #GFile objects - * @context: (nullable): a #GAppLaunchContext or %NULL - * @error: a #GError - * - * Launches the application. Passes @files to the launched application - * as arguments, using the optional @context to get information - * about the details of the launcher (like what screen it is on). - * On error, @error will be set accordingly. - * - * To launch the application without arguments pass a %NULL @files list. - * - * Note that even if the launch is successful the application launched - * can fail to start if it runs into problems during startup. There is - * no way to detect this. - * - * Some URIs can be changed when passed through a GFile (for instance - * unsupported URIs with strange formats like mailto:), so if you have - * a textual URI you want to pass in as argument, consider using - * g_app_info_launch_uris() instead. - * - * The launched application inherits the environment of the launching - * process, but it can be modified with g_app_launch_context_setenv() - * and g_app_launch_context_unsetenv(). - * - * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` - * environment variable with the path of the launched desktop file and - * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched - * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, - * should it be inherited by further processes. The `DISPLAY` and - * `DESKTOP_STARTUP_ID` environment variables are also set, based - * on information provided in @context. - * - * Returns: %TRUE on successful launch, %FALSE otherwise. - */ - - -/** - * g_app_info_launch_default_for_uri: - * @uri: the uri to show - * @context: (nullable): an optional #GAppLaunchContext - * @error: (nullable): return location for an error, or %NULL - * - * Utility function that launches the default application - * registered to handle the specified uri. Synchronous I/O - * is done on the uri to detect the type of the file if - * required. - * - * The D-Bus–activated applications don't have to be started if your application - * terminates too soon after this function. To prevent this, use - * g_app_info_launch_default_for_uri_async() instead. - * - * Returns: %TRUE on success, %FALSE on error. - */ - - -/** - * g_app_info_launch_default_for_uri_async: - * @uri: the uri to show - * @context: (nullable): an optional #GAppLaunchContext - * @cancellable: (nullable): a #GCancellable - * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done - * @user_data: (nullable): data to pass to @callback - * - * Async version of g_app_info_launch_default_for_uri(). - * - * This version is useful if you are interested in receiving - * error information in the case where the application is - * sandboxed and the portal may present an application chooser - * dialog to the user. - * - * This is also useful if you want to be sure that the D-Bus–activated - * applications are really started before termination and if you are interested - * in receiving error information from their activation. - * - * Since: 2.50 - */ - - -/** - * g_app_info_launch_default_for_uri_finish: - * @result: a #GAsyncResult - * @error: (nullable): return location for an error, or %NULL - * - * Finishes an asynchronous launch-default-for-uri operation. - * - * Returns: %TRUE if the launch was successful, %FALSE if @error is set - * Since: 2.50 - */ - - -/** - * g_app_info_launch_uris: - * @appinfo: a #GAppInfo - * @uris: (nullable) (element-type utf8): a #GList containing URIs to launch. - * @context: (nullable): a #GAppLaunchContext or %NULL - * @error: a #GError - * - * Launches the application. This passes the @uris to the launched application - * as arguments, using the optional @context to get information - * about the details of the launcher (like what screen it is on). - * On error, @error will be set accordingly. - * - * To launch the application without arguments pass a %NULL @uris list. - * - * Note that even if the launch is successful the application launched - * can fail to start if it runs into problems during startup. There is - * no way to detect this. - * - * Returns: %TRUE on successful launch, %FALSE otherwise. - */ - - -/** - * g_app_info_launch_uris_async: - * @appinfo: a #GAppInfo - * @uris: (nullable) (element-type utf8): a #GList containing URIs to launch. - * @context: (nullable): a #GAppLaunchContext or %NULL - * @cancellable: (nullable): a #GCancellable - * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done - * @user_data: (nullable): data to pass to @callback - * - * Async version of g_app_info_launch_uris(). - * - * The @callback is invoked immediately after the application launch, but it - * waits for activation in case of D-Bus–activated applications and also provides - * extended error information for sandboxed applications, see notes for - * g_app_info_launch_default_for_uri_async(). - * - * Since: 2.60 - */ - - -/** - * g_app_info_launch_uris_finish: - * @appinfo: a #GAppInfo - * @result: a #GAsyncResult - * @error: (nullable): a #GError - * - * Finishes a g_app_info_launch_uris_async() operation. - * - * Returns: %TRUE on successful launch, %FALSE otherwise. - * Since: 2.60 - */ - - -/** - * g_app_info_monitor_get: - * - * Gets the #GAppInfoMonitor for the current thread-default main - * context. - * - * The #GAppInfoMonitor will emit a "changed" signal in the - * thread-default main context whenever the list of installed - * applications (as reported by g_app_info_get_all()) may have changed. - * - * You must only call g_object_unref() on the return value from under - * the same main context as you created it. - * - * Returns: (transfer full): a reference to a #GAppInfoMonitor - * Since: 2.40 - */ - - -/** - * g_app_info_remove_supports_type: - * @appinfo: a #GAppInfo. - * @content_type: a string. - * @error: a #GError. - * - * Removes a supported type from an application, if possible. - * - * Returns: %TRUE on success, %FALSE on error. - */ - - -/** - * g_app_info_reset_type_associations: - * @content_type: a content type - * - * Removes all changes to the type associations done by - * g_app_info_set_as_default_for_type(), - * g_app_info_set_as_default_for_extension(), - * g_app_info_add_supports_type() or - * g_app_info_remove_supports_type(). - * - * Since: 2.20 - */ - - -/** - * g_app_info_set_as_default_for_extension: - * @appinfo: a #GAppInfo. - * @extension: (type filename): a string containing the file extension - * (without the dot). - * @error: a #GError. - * - * Sets the application as the default handler for the given file extension. - * - * Returns: %TRUE on success, %FALSE on error. - */ - - -/** - * g_app_info_set_as_default_for_type: - * @appinfo: a #GAppInfo. - * @content_type: the content type. - * @error: a #GError. - * - * Sets the application as the default handler for a given type. - * - * Returns: %TRUE on success, %FALSE on error. - */ - - -/** - * g_app_info_set_as_last_used_for_type: - * @appinfo: a #GAppInfo. - * @content_type: the content type. - * @error: a #GError. - * - * Sets the application as the last used application for a given type. - * This will make the application appear as first in the list returned - * by g_app_info_get_recommended_for_type(), regardless of the default - * application for that content type. - * - * Returns: %TRUE on success, %FALSE on error. - */ - - -/** - * g_app_info_should_show: - * @appinfo: a #GAppInfo. - * - * Checks if the application info should be shown in menus that - * list available applications. - * - * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise. - */ - - -/** - * g_app_info_supports_files: - * @appinfo: a #GAppInfo. - * - * Checks if the application accepts files as arguments. - * - * Returns: %TRUE if the @appinfo supports files. - */ - - -/** - * g_app_info_supports_uris: - * @appinfo: a #GAppInfo. - * - * Checks if the application supports reading files and directories from URIs. - * - * Returns: %TRUE if the @appinfo supports URIs. - */ - - -/** - * g_app_launch_context_get_display: - * @context: a #GAppLaunchContext - * @info: a #GAppInfo - * @files: (element-type GFile): a #GList of #GFile objects - * - * Gets the display string for the @context. This is used to ensure new - * applications are started on the same display as the launching - * application, by setting the `DISPLAY` environment variable. - * - * Returns: (nullable): a display string for the display. - */ - - -/** - * g_app_launch_context_get_environment: - * @context: a #GAppLaunchContext - * - * Gets the complete environment variable list to be passed to - * the child process when @context is used to launch an application. - * This is a %NULL-terminated array of strings, where each string has - * the form `KEY=VALUE`. - * - * Returns: (array zero-terminated=1) (element-type filename) (transfer full): - * the child's environment - * Since: 2.32 - */ - - -/** - * g_app_launch_context_get_startup_notify_id: - * @context: a #GAppLaunchContext - * @info: a #GAppInfo - * @files: (element-type GFile): a #GList of of #GFile objects - * - * Initiates startup notification for the application and returns the - * `DESKTOP_STARTUP_ID` for the launched operation, if supported. - * - * Startup notification IDs are defined in the - * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). - * - * Returns: (nullable): a startup notification ID for the application, or %NULL if - * not supported. - */ - - -/** - * g_app_launch_context_launch_failed: - * @context: a #GAppLaunchContext. - * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). - * - * Called when an application has failed to launch, so that it can cancel - * the application startup notification started in g_app_launch_context_get_startup_notify_id(). - */ - - -/** - * g_app_launch_context_new: - * - * Creates a new application launch context. This is not normally used, - * instead you instantiate a subclass of this, such as #GdkAppLaunchContext. - * - * Returns: a #GAppLaunchContext. - */ - - -/** - * g_app_launch_context_setenv: - * @context: a #GAppLaunchContext - * @variable: (type filename): the environment variable to set - * @value: (type filename): the value for to set the variable to. - * - * Arranges for @variable to be set to @value in the child's - * environment when @context is used to launch an application. - * - * Since: 2.32 - */ - - -/** - * g_app_launch_context_unsetenv: - * @context: a #GAppLaunchContext - * @variable: (type filename): the environment variable to remove - * - * Arranges for @variable to be unset in the child's environment - * when @context is used to launch an application. - * - * Since: 2.32 - */ - - -/** - * g_application_activate: - * @application: a #GApplication - * - * Activates the application. - * - * In essence, this results in the #GApplication::activate signal being - * emitted in the primary instance. - * - * The application must be registered before calling this function. - * - * Since: 2.28 - */ - - -/** - * g_application_add_main_option: - * @application: the #GApplication - * @long_name: the long name of an option used to specify it in a commandline - * @short_name: the short name of an option - * @flags: flags from #GOptionFlags - * @arg: the type of the option, as a #GOptionArg - * @description: the description for the option in `--help` output - * @arg_description: (nullable): the placeholder to use for the extra argument - * parsed by the option in `--help` output - * - * Add an option to be handled by @application. - * - * Calling this function is the equivalent of calling - * g_application_add_main_option_entries() with a single #GOptionEntry - * that has its arg_data member set to %NULL. - * - * The parsed arguments will be packed into a #GVariantDict which - * is passed to #GApplication::handle-local-options. If - * %G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also - * be sent to the primary instance. See - * g_application_add_main_option_entries() for more details. - * - * See #GOptionEntry for more documentation of the arguments. - * - * Since: 2.42 - */ - - -/** - * g_application_add_main_option_entries: - * @application: a #GApplication - * @entries: (array zero-terminated=1) (element-type GOptionEntry): a - * %NULL-terminated list of #GOptionEntrys - * - * Adds main option entries to be handled by @application. - * - * This function is comparable to g_option_context_add_main_entries(). - * - * After the commandline arguments are parsed, the - * #GApplication::handle-local-options signal will be emitted. At this - * point, the application can inspect the values pointed to by @arg_data - * in the given #GOptionEntrys. - * - * Unlike #GOptionContext, #GApplication supports giving a %NULL - * @arg_data for a non-callback #GOptionEntry. This results in the - * argument in question being packed into a #GVariantDict which is also - * passed to #GApplication::handle-local-options, where it can be - * inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is - * set, then the resulting dictionary is sent to the primary instance, - * where g_application_command_line_get_options_dict() will return it. - * This "packing" is done according to the type of the argument -- - * booleans for normal flags, strings for strings, bytestrings for - * filenames, etc. The packing only occurs if the flag is given (ie: we - * do not pack a "false" #GVariant in the case that a flag is missing). - * - * In general, it is recommended that all commandline arguments are - * parsed locally. The options dictionary should then be used to - * transmit the result of the parsing to the primary instance, where - * g_variant_dict_lookup() can be used. For local options, it is - * possible to either use @arg_data in the usual way, or to consult (and - * potentially remove) the option from the options dictionary. - * - * This function is new in GLib 2.40. Before then, the only real choice - * was to send all of the commandline arguments (options and all) to the - * primary instance for handling. #GApplication ignored them completely - * on the local side. Calling this function "opts in" to the new - * behaviour, and in particular, means that unrecognised options will be - * treated as errors. Unrecognised options have never been ignored when - * %G_APPLICATION_HANDLES_COMMAND_LINE is unset. - * - * If #GApplication::handle-local-options needs to see the list of - * filenames, then the use of %G_OPTION_REMAINING is recommended. If - * @arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into - * the options dictionary. If you do use %G_OPTION_REMAINING then you - * need to handle these arguments for yourself because once they are - * consumed, they will no longer be visible to the default handling - * (which treats them as filenames to be opened). - * - * It is important to use the proper GVariant format when retrieving - * the options with g_variant_dict_lookup(): - * - for %G_OPTION_ARG_NONE, use `b` - * - for %G_OPTION_ARG_STRING, use `&s` - * - for %G_OPTION_ARG_INT, use `i` - * - for %G_OPTION_ARG_INT64, use `x` - * - for %G_OPTION_ARG_DOUBLE, use `d` - * - for %G_OPTION_ARG_FILENAME, use `^&ay` - * - for %G_OPTION_ARG_STRING_ARRAY, use `^a&s` - * - for %G_OPTION_ARG_FILENAME_ARRAY, use `^a&ay` - * - * Since: 2.40 - */ - - -/** - * g_application_add_option_group: - * @application: the #GApplication - * @group: (transfer full): a #GOptionGroup - * - * Adds a #GOptionGroup to the commandline handling of @application. - * - * This function is comparable to g_option_context_add_group(). - * - * Unlike g_application_add_main_option_entries(), this function does - * not deal with %NULL @arg_data and never transmits options to the - * primary instance. - * - * The reason for that is because, by the time the options arrive at the - * primary instance, it is typically too late to do anything with them. - * Taking the GTK option group as an example: GTK will already have been - * initialised by the time the #GApplication::command-line handler runs. - * In the case that this is not the first-running instance of the - * application, the existing instance may already have been running for - * a very long time. - * - * This means that the options from #GOptionGroup are only really usable - * in the case that the instance of the application being run is the - * first instance. Passing options like `--display=` or `--gdk-debug=` - * on future runs will have no effect on the existing primary instance. - * - * Calling this function will cause the options in the supplied option - * group to be parsed, but it does not cause you to be "opted in" to the - * new functionality whereby unrecognised options are rejected even if - * %G_APPLICATION_HANDLES_COMMAND_LINE was given. - * - * Since: 2.40 - */ - - -/** - * g_application_bind_busy_property: - * @application: a #GApplication - * @object: (type GObject.Object): a #GObject - * @property: the name of a boolean property of @object - * - * Marks @application as busy (see g_application_mark_busy()) while - * @property on @object is %TRUE. - * - * The binding holds a reference to @application while it is active, but - * not to @object. Instead, the binding is destroyed when @object is - * finalized. - * - * Since: 2.44 - */ - - -/** - * g_application_command_line_create_file_for_arg: - * @cmdline: a #GApplicationCommandLine - * @arg: (type filename): 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) (optional): the length of the arguments array, or %NULL - * - * Gets the list of arguments that was passed on the command line. - * - * The strings in the array may contain non-UTF-8 data on UNIX (such as - * filenames or arguments given in the system locale) but are always in - * UTF-8 on Windows. - * - * If you wish to use the return value with #GOptionContext, you must - * use g_option_context_parse_strv(). - * - * The return value is %NULL-terminated and should be freed using - * g_strfreev(). - * - * Returns: (array length=argc) (element-type filename) (transfer full): - * the string array containing the arguments (the argv) - * Since: 2.28 - */ - - -/** - * g_application_command_line_get_cwd: - * @cmdline: a #GApplicationCommandLine - * - * Gets the working directory of the command line invocation. - * The string may contain non-utf8 data. - * - * It is possible that the remote application did not send a working - * directory, so this may be %NULL. - * - * The return value should not be modified or freed and is valid for as - * long as @cmdline exists. - * - * Returns: (nullable) (type filename): the current directory, or %NULL - * Since: 2.28 - */ - - -/** - * g_application_command_line_get_environ: - * @cmdline: a #GApplicationCommandLine - * - * Gets the contents of the 'environ' variable of the command line - * invocation, as would be returned by g_get_environ(), ie as a - * %NULL-terminated list of strings in the form 'NAME=VALUE'. - * The strings may contain non-utf8 data. - * - * The remote application usually does not send an environment. Use - * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag - * set it is possible that the environment is still not available (due - * to invocation messages from other applications). - * - * The return value should not be modified or freed and is valid for as - * long as @cmdline exists. - * - * See g_application_command_line_getenv() if you are only interested - * in the value of a single environment variable. - * - * Returns: (array zero-terminated=1) (element-type filename) (transfer none): - * the environment strings, or %NULL if they were not sent - * Since: 2.28 - */ - - -/** - * g_application_command_line_get_exit_status: - * @cmdline: a #GApplicationCommandLine - * - * Gets the exit status of @cmdline. See - * g_application_command_line_set_exit_status() for more information. - * - * Returns: the exit status - * Since: 2.28 - */ - - -/** - * g_application_command_line_get_is_remote: - * @cmdline: a #GApplicationCommandLine - * - * Determines if @cmdline represents a remote invocation. - * - * Returns: %TRUE if the invocation was remote - * Since: 2.28 - */ - - -/** - * g_application_command_line_get_options_dict: - * @cmdline: a #GApplicationCommandLine - * - * Gets the options there were passed to g_application_command_line(). - * - * If you did not override local_command_line() then these are the same - * options that were parsed according to the #GOptionEntrys added to the - * application with g_application_add_main_option_entries() and possibly - * modified from your GApplication::handle-local-options handler. - * - * If no options were sent then an empty dictionary is returned so that - * you don't need to check for %NULL. - * - * Returns: (transfer none): a #GVariantDict with the options - * Since: 2.40 - */ - - -/** - * g_application_command_line_get_platform_data: - * @cmdline: #GApplicationCommandLine - * - * Gets the platform data associated with the invocation of @cmdline. - * - * This is a #GVariant dictionary containing information about the - * context in which the invocation occurred. It typically contains - * information like the current working directory and the startup - * notification ID. - * - * For local invocation, it will be %NULL. - * - * Returns: (nullable): the platform data, or %NULL - * Since: 2.28 - */ - - -/** - * 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 D-Bus 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: (nullable) (transfer full): a #GInputStream for stdin - * Since: 2.34 - */ - - -/** - * g_application_command_line_getenv: - * @cmdline: a #GApplicationCommandLine - * @name: (type filename): the environment variable to get - * - * Gets the value of a particular environment variable of the command - * line invocation, as would be returned by g_getenv(). The strings may - * contain non-utf8 data. - * - * The remote application usually does not send an environment. Use - * %G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag - * set it is possible that the environment is still not available (due - * to invocation messages from other applications). - * - * The return value should not be modified or freed and is valid for as - * long as @cmdline exists. - * - * Returns: (nullable): the value of the variable, or %NULL if unset or unsent - * Since: 2.28 - */ - - -/** - * g_application_command_line_print: - * @cmdline: a #GApplicationCommandLine - * @format: a printf-style format string - * @...: arguments, as per @format - * - * Formats a message and prints it using the stdout print handler in the - * invoking process. - * - * If @cmdline is a local invocation then this is exactly equivalent to - * g_print(). If @cmdline is remote then this is equivalent to calling - * g_print() in the invoking process. - * - * Since: 2.28 - */ - - -/** - * g_application_command_line_printerr: - * @cmdline: a #GApplicationCommandLine - * @format: a printf-style format string - * @...: arguments, as per @format - * - * Formats a message and prints it using the stderr print handler in the - * invoking process. - * - * If @cmdline is a local invocation then this is exactly equivalent to - * g_printerr(). If @cmdline is remote then this is equivalent to - * calling g_printerr() in the invoking process. - * - * Since: 2.28 - */ - - -/** - * g_application_command_line_set_exit_status: - * @cmdline: a #GApplicationCommandLine - * @exit_status: the exit status - * - * Sets the exit status that will be used when the invoking process - * exits. - * - * The return value of the #GApplication::command-line signal is - * passed to this function when the handler returns. This is the usual - * way of setting the exit status. - * - * In the event that you want the remote invocation to continue running - * and want to decide on the exit status in the future, you can use this - * call. For the case of a remote invocation, the remote process will - * typically exit when the last reference is dropped on @cmdline. The - * exit status of the remote process will be equal to the last value - * that was set with this function. - * - * In the case that the commandline invocation is local, the situation - * is slightly more complicated. If the commandline invocation results - * in the mainloop running (ie: because the use-count of the application - * increased to a non-zero value) then the application is considered to - * have been 'successful' in a certain sense, and the exit status is - * always zero. If the application use count is zero, though, the exit - * status of the local #GApplicationCommandLine is used. - * - * Since: 2.28 - */ - - -/** - * g_application_get_application_id: - * @application: a #GApplication - * - * Gets the unique identifier for @application. - * - * Returns: (nullable): the identifier for @application, owned by @application - * Since: 2.28 - */ - - -/** - * g_application_get_dbus_connection: - * @application: a #GApplication - * - * Gets the #GDBusConnection being used by the application, or %NULL. - * - * If #GApplication is using its D-Bus backend then this function will - * return the #GDBusConnection being used for uniqueness and - * communication with the desktop environment and other instances of the - * application. - * - * If #GApplication is not using D-Bus then this function will return - * %NULL. This includes the situation where the D-Bus backend would - * normally be in use but we were unable to connect to the bus. - * - * This function must not be called before the application has been - * registered. See g_application_get_is_registered(). - * - * Returns: (nullable) (transfer none): a #GDBusConnection, or %NULL - * Since: 2.34 - */ - - -/** - * g_application_get_dbus_object_path: - * @application: a #GApplication - * - * Gets the D-Bus object path being used by the application, or %NULL. - * - * If #GApplication is using its D-Bus backend then this function will - * return the D-Bus object path that #GApplication is using. If the - * application is the primary instance then there is an object published - * at this path. If the application is not the primary instance then - * the result of this function is undefined. - * - * If #GApplication is not using D-Bus then this function will return - * %NULL. This includes the situation where the D-Bus backend would - * normally be in use but we were unable to connect to the bus. - * - * This function must not be called before the application has been - * registered. See g_application_get_is_registered(). - * - * Returns: (nullable): the object path, or %NULL - * Since: 2.34 - */ - - -/** - * g_application_get_default: - * - * Returns the default #GApplication instance for this process. - * - * Normally there is only one #GApplication per process and it becomes - * the default when it is created. You can exercise more control over - * this by using g_application_set_default(). - * - * If there is no default application then %NULL is returned. - * - * Returns: (nullable) (transfer none): the default application for this process, or %NULL - * Since: 2.32 - */ - - -/** - * g_application_get_flags: - * @application: a #GApplication - * - * Gets the flags for @application. - * - * See #GApplicationFlags. - * - * Returns: the flags for @application - * Since: 2.28 - */ - - -/** - * g_application_get_inactivity_timeout: - * @application: a #GApplication - * - * Gets the current inactivity timeout for the application. - * - * This is the amount of time (in milliseconds) after the last call to - * g_application_release() before the application stops running. - * - * Returns: the timeout, in milliseconds - * Since: 2.28 - */ - - -/** - * g_application_get_is_busy: - * @application: a #GApplication - * - * Gets the application's current busy state, as set through - * g_application_mark_busy() or g_application_bind_busy_property(). - * - * Returns: %TRUE if @application is currently marked as busy - * Since: 2.44 - */ - - -/** - * g_application_get_is_registered: - * @application: a #GApplication - * - * Checks if @application is registered. - * - * An application is registered if g_application_register() has been - * successfully called. - * - * Returns: %TRUE if @application is registered - * Since: 2.28 - */ - - -/** - * g_application_get_is_remote: - * @application: a #GApplication - * - * Checks if @application is remote. - * - * If @application is remote then it means that another instance of - * application already exists (the 'primary' instance). Calls to - * perform actions on @application will result in the actions being - * performed by the primary instance. - * - * The value of this property cannot be accessed before - * g_application_register() has been called. See - * g_application_get_is_registered(). - * - * Returns: %TRUE if @application is remote - * Since: 2.28 - */ - - -/** - * g_application_get_resource_base_path: - * @application: a #GApplication - * - * Gets the resource base path of @application. - * - * See g_application_set_resource_base_path() for more information. - * - * Returns: (nullable): the base resource path, if one is set - * Since: 2.42 - */ - - -/** - * g_application_hold: - * @application: a #GApplication - * - * Increases the use count of @application. - * - * Use this function to indicate that the application has a reason to - * continue to run. For example, g_application_hold() is called by GTK+ - * when a toplevel window is on the screen. - * - * To cancel the hold, call g_application_release(). - */ - - -/** - * g_application_id_is_valid: - * @application_id: a potential application identifier - * - * Checks if @application_id is a valid application identifier. - * - * A valid ID is required for calls to g_application_new() and - * g_application_set_application_id(). - * - * Application identifiers follow the same format as - * [D-Bus well-known bus names](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). - * For convenience, the restrictions on application identifiers are - * reproduced here: - * - * - Application identifiers are composed of 1 or more elements separated by a - * period (`.`) character. All elements must contain at least one character. - * - * - Each element must only contain the ASCII characters `[A-Z][a-z][0-9]_-`, - * with `-` discouraged in new application identifiers. Each element must not - * begin with a digit. - * - * - Application identifiers must contain at least one `.` (period) character - * (and thus at least two elements). - * - * - Application identifiers must not begin with a `.` (period) character. - * - * - Application identifiers must not exceed 255 characters. - * - * Note that the hyphen (`-`) character is allowed in application identifiers, - * but is problematic or not allowed in various specifications and APIs that - * refer to D-Bus, such as - * [Flatpak application IDs](http://docs.flatpak.org/en/latest/introduction.html#identifiers), - * the - * [`DBusActivatable` interface in the Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus), - * and the convention that an application's "main" interface and object path - * resemble its application identifier and bus name. To avoid situations that - * require special-case handling, it is recommended that new application - * identifiers consistently replace hyphens with underscores. - * - * Like D-Bus interface names, application identifiers should start with the - * reversed DNS domain name of the author of the interface (in lower-case), and - * it is conventional for the rest of the application identifier to consist of - * words run together, with initial capital letters. - * - * As with D-Bus interface names, if the author's DNS domain name contains - * hyphen/minus characters they should be replaced by underscores, and if it - * contains leading digits they should be escaped by prepending an underscore. - * For example, if the owner of 7-zip.org used an application identifier for an - * archiving application, it might be named `org._7_zip.Archiver`. - * - * Returns: %TRUE if @application_id is valid - */ - - -/** - * 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(). - * - * The application must be registered before calling this function. - * - * Since: 2.38 - */ - - -/** - * g_application_new: - * @application_id: (nullable): the application id - * @flags: the application flags - * - * Creates a new #GApplication instance. - * - * If non-%NULL, the application id must be valid. See - * g_application_id_is_valid(). - * - * If no application ID is given then some features of #GApplication - * (most notably application uniqueness) will be disabled. - * - * Returns: a new #GApplication instance - */ - - -/** - * g_application_open: - * @application: a #GApplication - * @files: (array length=n_files): an array of #GFiles to open - * @n_files: the length of the @files array - * @hint: a hint (or ""), but never %NULL - * - * Opens the given files. - * - * In essence, this results in the #GApplication::open signal being emitted - * in the primary instance. - * - * @n_files must be greater than zero. - * - * @hint is simply passed through to the ::open signal. It is - * intended to be used by applications that have multiple modes for - * opening files (eg: "view" vs "edit", etc). Unless you have a need - * for this functionality, you should use "". - * - * The application must be registered before calling this function - * and it must have the %G_APPLICATION_HANDLES_OPEN flag set. - * - * Since: 2.28 - */ - - -/** - * g_application_quit: - * @application: a #GApplication - * - * Immediately quits the application. - * - * Upon return to the mainloop, g_application_run() will return, - * calling only the 'shutdown' function before doing so. - * - * The hold count is ignored. - * Take care if your code has called g_application_hold() on the application and - * is therefore still expecting it to exist. - * (Note that you may have called g_application_hold() indirectly, for example - * through gtk_application_add_window().) - * - * The result of calling g_application_run() again after it returns is - * unspecified. - * - * Since: 2.32 - */ - - -/** - * g_application_register: - * @application: a #GApplication - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a pointer to a NULL #GError, or %NULL - * - * Attempts registration of the application. - * - * This is the point at which the application discovers if it is the - * primary instance or merely acting as a remote for an already-existing - * primary instance. This is implemented by attempting to acquire the - * application identifier as a unique bus name on the session bus using - * GDBus. - * - * If there is no application ID or if %G_APPLICATION_NON_UNIQUE was - * given, then this process will always become the primary instance. - * - * Due to the internal architecture of GDBus, method calls can be - * dispatched at any time (even if a main loop is not running). For - * this reason, you must ensure that any object paths that you wish to - * register are registered before calling this function. - * - * If the application has already been registered then %TRUE is - * returned with no work performed. - * - * The #GApplication::startup signal is emitted if registration succeeds - * and @application is the primary instance (including the non-unique - * case). - * - * In the event of an error (such as @cancellable being cancelled, or a - * failure to connect to the session bus), %FALSE is returned and @error - * is set appropriately. - * - * Note: the return value of this function is not an indicator that this - * instance is or is not the primary instance of the application. See - * g_application_get_is_remote() for that. - * - * Returns: %TRUE if registration succeeded - * Since: 2.28 - */ - - -/** - * g_application_release: - * @application: a #GApplication - * - * Decrease the use count of @application. - * - * When the use count reaches zero, the application will stop running. - * - * Never call this function except to cancel the effect of a previous - * call to g_application_hold(). - */ - - -/** - * g_application_run: - * @application: a #GApplication - * @argc: the argc from main() (or 0 if @argv is %NULL) - * @argv: (array length=argc) (element-type filename) (nullable): - * the argv from main(), or %NULL - * - * Runs the application. - * - * This function is intended to be run from main() and its return value - * is intended to be returned by main(). Although you are expected to pass - * the @argc, @argv parameters from main() to this function, it is possible - * to pass %NULL if @argv is not available or commandline handling is not - * required. Note that on Windows, @argc and @argv are ignored, and - * g_win32_get_command_line() is called internally (for proper support - * of Unicode commandline arguments). - * - * #GApplication will attempt to parse the commandline arguments. You - * can add commandline flags to the list of recognised options by way of - * g_application_add_main_option_entries(). After this, the - * #GApplication::handle-local-options signal is emitted, from which the - * application can inspect the values of its #GOptionEntrys. - * - * #GApplication::handle-local-options is a good place to handle options - * such as `--version`, where an immediate reply from the local process is - * desired (instead of communicating with an already-running instance). - * A #GApplication::handle-local-options handler can stop further processing - * by returning a non-negative value, which then becomes the exit status of - * the process. - * - * What happens next depends on the flags: if - * %G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining - * commandline arguments are sent to the primary instance, where a - * #GApplication::command-line signal is emitted. Otherwise, the - * remaining commandline arguments are assumed to be a list of files. - * If there are no files listed, the application is activated via the - * #GApplication::activate signal. If there are one or more files, and - * %G_APPLICATION_HANDLES_OPEN was specified then the files are opened - * via the #GApplication::open signal. - * - * If you are interested in doing more complicated local handling of the - * commandline then you should implement your own #GApplication subclass - * and override local_command_line(). In this case, you most likely want - * to return %TRUE from your local_command_line() implementation to - * suppress the default handling. See - * [gapplication-example-cmdline2.c][https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c] - * for an example. - * - * If, after the above is done, the use count of the application is zero - * then the exit status is returned immediately. If the use count is - * 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 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]. - * - * Much like g_main_loop_run(), this function will acquire the main context - * for the duration that the application is running. - * - * Since 2.40, applications that are not explicitly flagged as services - * or launchers (ie: neither %G_APPLICATION_IS_SERVICE or - * %G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the - * default handler for local_command_line) if "--gapplication-service" - * was given in the command line. If this flag is present then normal - * commandline processing is interrupted and the - * %G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise" - * solution whereby running an application directly from the commandline - * will invoke it in the normal way (which can be useful for debugging) - * while still allowing applications to be D-Bus activated in service - * mode. The D-Bus service file should invoke the executable with - * "--gapplication-service" as the sole commandline argument. This - * approach is suitable for use by most graphical applications but - * should not be used from applications like editors that need precise - * control over when processes invoked via the commandline will exit and - * what their exit status will be. - * - * Returns: the exit status - * Since: 2.28 - */ - - -/** - * g_application_send_notification: - * @application: a #GApplication - * @id: (nullable): id of the notification, or %NULL - * @notification: the #GNotification to send - * - * Sends a notification on behalf of @application to the desktop shell. - * There is no guarantee that the notification is displayed immediately, - * or even at all. - * - * Notifications may persist after the application exits. It will be - * D-Bus-activated when the notification or one of its actions is - * activated. - * - * Modifying @notification after this call has no effect. However, the - * object can be reused for a later call to this function. - * - * @id may be any string that uniquely identifies the event for the - * application. It does not need to be in any special format. For - * example, "new-message" might be appropriate for a notification about - * new messages. - * - * If a previous notification was sent with the same @id, it will be - * replaced with @notification and shown again as if it was a new - * notification. This works even for notifications sent from a previous - * execution of the application, as long as @id is the same string. - * - * @id may be %NULL, but it is impossible to replace or withdraw - * notifications without an id. - * - * If @notification is no longer relevant, it can be withdrawn with - * g_application_withdraw_notification(). - * - * Since: 2.40 - */ - - -/** - * g_application_set_action_group: - * @application: a #GApplication - * @action_group: (nullable): a #GActionGroup, or %NULL - * - * This used to be how actions were associated with a #GApplication. - * Now there is #GActionMap for that. - * - * Since: 2.28 - * Deprecated: 2.32: Use the #GActionMap interface instead. Never ever - * mix use of this API with use of #GActionMap on the same @application - * or things will go very badly wrong. This function is known to - * introduce buggy behaviour (ie: signals not emitted on changes to the - * action group), so you should really use #GActionMap instead. - */ - - -/** - * g_application_set_application_id: - * @application: a #GApplication - * @application_id: (nullable): the identifier for @application - * - * Sets the unique identifier for @application. - * - * The application id can only be modified if @application has not yet - * been registered. - * - * If non-%NULL, the application id must be valid. See - * g_application_id_is_valid(). - * - * Since: 2.28 - */ - - -/** - * g_application_set_default: - * @application: (nullable): the application to set as default, or %NULL - * - * Sets or unsets the default application for the process, as returned - * by g_application_get_default(). - * - * This function does not take its own reference on @application. If - * @application is destroyed then the default application will revert - * back to %NULL. - * - * Since: 2.32 - */ - - -/** - * g_application_set_flags: - * @application: a #GApplication - * @flags: the flags for @application - * - * Sets the flags for @application. - * - * The flags can only be modified if @application has not yet been - * registered. - * - * See #GApplicationFlags. - * - * Since: 2.28 - */ - - -/** - * g_application_set_inactivity_timeout: - * @application: a #GApplication - * @inactivity_timeout: the timeout, in milliseconds - * - * Sets the current inactivity timeout for the application. - * - * This is the amount of time (in milliseconds) after the last call to - * g_application_release() before the application stops running. - * - * This call has no side effects of its own. The value set here is only - * used for next time g_application_release() drops the use count to - * zero. Any timeouts currently in progress are not impacted. - * - * Since: 2.28 - */ - - -/** - * g_application_set_option_context_description: - * @application: the #GApplication - * @description: (nullable): a string to be shown in `--help` output - * after the list of options, or %NULL - * - * Adds a description to the @application option context. - * - * See g_option_context_set_description() for more information. - * - * Since: 2.56 - */ - - -/** - * g_application_set_option_context_parameter_string: - * @application: the #GApplication - * @parameter_string: (nullable): a string which is displayed - * in the first line of `--help` output, after the usage summary `programname [OPTION...]`. - * - * Sets the parameter string to be used by the commandline handling of @application. - * - * This function registers the argument to be passed to g_option_context_new() - * when the internal #GOptionContext of @application is created. - * - * See g_option_context_new() for more information about @parameter_string. - * - * Since: 2.56 - */ - - -/** - * g_application_set_option_context_summary: - * @application: the #GApplication - * @summary: (nullable): a string to be shown in `--help` output - * before the list of options, or %NULL - * - * Adds a summary to the @application option context. - * - * See g_option_context_set_summary() for more information. - * - * Since: 2.56 - */ - - -/** - * g_application_set_resource_base_path: - * @application: a #GApplication - * @resource_path: (nullable): the resource path to use - * - * Sets (or unsets) the base resource path of @application. - * - * The path is used to automatically load various [application - * resources][gresource] such as menu layouts and action descriptions. - * The various types of resources will be found at fixed names relative - * to the given base path. - * - * By default, the resource base path is determined from the application - * ID by prefixing '/' and replacing each '.' with '/'. This is done at - * the time that the #GApplication object is constructed. Changes to - * the application ID after that point will not have an impact on the - * resource base path. - * - * As an example, if the application has an ID of "org.example.app" then - * the default resource base path will be "/org/example/app". If this - * is a #GtkApplication (and you have not manually changed the path) - * then Gtk will then search for the menus of the application at - * "/org/example/app/gtk/menus.ui". - * - * See #GResource for more information about adding resources to your - * application. - * - * You can disable automatic resource loading functionality by setting - * the path to %NULL. - * - * Changing the resource base path once the application is running is - * not recommended. The point at which the resource path is consulted - * for forming paths for various purposes is unspecified. When writing - * a sub-class of #GApplication you should either set the - * #GApplication:resource-base-path property at construction time, or call - * this function during the instance initialization. Alternatively, you - * can call this function in the #GApplicationClass.startup virtual function, - * before chaining up to the parent implementation. - * - * Since: 2.42 - */ - - -/** - * g_application_unbind_busy_property: - * @application: a #GApplication - * @object: (type GObject.Object): a #GObject - * @property: the name of a boolean property of @object - * - * Destroys a binding between @property and the busy state of - * @application that was previously created with - * g_application_bind_busy_property(). - * - * Since: 2.44 - */ - - -/** - * 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_application_withdraw_notification: - * @application: a #GApplication - * @id: id of a previously sent notification - * - * Withdraws a notification that was sent with - * g_application_send_notification(). - * - * This call does nothing if a notification with @id doesn't exist or - * the notification was never sent. - * - * This function works even for notifications sent in previous - * executions of this application, as long @id is the same as it was for - * the sent notification. - * - * Note that notifications are dismissed when the user clicks on one - * of the buttons in a notification or triggers its default action, so - * there is no need to explicitly withdraw the notification in that case. - * - * Since: 2.40 - */ - - -/** - * g_async_initable_init_async: - * @initable: a #GAsyncInitable. - * @io_priority: the [I/O priority][io-priority] of the operation - * @cancellable: 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 - * - * Starts asynchronous initialization of the object implementing the - * interface. This must be done before any real use of the object after - * initial construction. If the object also implements #GInitable you can - * optionally call g_initable_init() instead. - * - * This method is intended for language bindings. If writing in C, - * g_async_initable_new_async() should typically be used instead. - * - * When the initialization is finished, @callback will be called. You can - * then call g_async_initable_init_finish() to get the result of the - * initialization. - * - * Implementations may also support cancellation. If @cancellable is not - * %NULL, then initialization can be cancelled by triggering the cancellable - * object from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL, and - * the object doesn't support cancellable initialization, the error - * %G_IO_ERROR_NOT_SUPPORTED will be returned. - * - * As with #GInitable, if the object is not initialized, or initialization - * returns with an error, then all operations on the object except - * g_object_ref() and g_object_unref() are considered to be invalid, and - * have undefined behaviour. They will often fail with g_critical() or - * g_warning(), but this must not be relied on. - * - * Callers should not assume that a class which implements #GAsyncInitable can - * be initialized multiple times; for more information, see g_initable_init(). - * If a class explicitly supports being initialized multiple times, - * implementation requires yielding all subsequent calls to init_async() on the - * results of the first call. - * - * For classes that also support the #GInitable interface, the default - * implementation of this method will run the g_initable_init() function - * in a thread, so if you want to support asynchronous initialization via - * threads, just implement the #GAsyncInitable interface without overriding - * any interface methods. - * - * Since: 2.22 - */ - - -/** - * g_async_initable_init_finish: - * @initable: a #GAsyncInitable. - * @res: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes asynchronous initialization and returns the result. - * See g_async_initable_init_async(). - * - * Returns: %TRUE if successful. If an error has occurred, this function - * will return %FALSE and set @error appropriately if present. - * Since: 2.22 - */ - - -/** - * g_async_initable_new_async: - * @object_type: a #GType supporting #GAsyncInitable. - * @io_priority: the [I/O priority][io-priority] of the operation - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is - * finished - * @user_data: the data to pass to callback function - * @first_property_name: (nullable): the name of the first property, or %NULL if no - * properties - * @...: the value of the first property, followed by other property - * value pairs, and ended by %NULL. - * - * Helper function for constructing #GAsyncInitable object. This is - * similar to g_object_new() but also initializes the object asynchronously. - * - * When the initialization is finished, @callback will be called. You can - * then call g_async_initable_new_finish() to get the new object and check - * for any errors. - * - * Since: 2.22 - */ - - -/** - * g_async_initable_new_finish: - * @initable: the #GAsyncInitable from the callback - * @res: the #GAsyncResult from the callback - * @error: return location for errors, or %NULL to ignore - * - * Finishes the async construction for the various g_async_initable_new - * calls, returning the created object or %NULL on error. - * - * Returns: (type GObject.Object) (transfer full): a newly created #GObject, - * or %NULL on error. Free with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_async_initable_new_valist_async: - * @object_type: a #GType supporting #GAsyncInitable. - * @first_property_name: the name of the first property, followed by - * the value, and other property value pairs, and ended by %NULL. - * @var_args: The var args list generated from @first_property_name. - * @io_priority: the [I/O priority][io-priority] of the operation - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is - * finished - * @user_data: the data to pass to callback function - * - * Helper function for constructing #GAsyncInitable object. This is - * similar to g_object_new_valist() but also initializes the object - * asynchronously. - * - * When the initialization is finished, @callback will be called. You can - * then call g_async_initable_new_finish() to get the new object and check - * for any errors. - * - * Since: 2.22 - */ - - -/** - * g_async_initable_newv_async: - * @object_type: a #GType supporting #GAsyncInitable. - * @n_parameters: the number of parameters in @parameters - * @parameters: the parameters to use to construct the object - * @io_priority: the [I/O priority][io-priority] of the operation - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is - * finished - * @user_data: the data to pass to callback function - * - * Helper function for constructing #GAsyncInitable object. This is - * similar to g_object_newv() but also initializes the object asynchronously. - * - * When the initialization is finished, @callback will be called. You can - * then call g_async_initable_new_finish() to get the new object and check - * for any errors. - * - * Since: 2.22 - * Deprecated: 2.54: Use g_object_new_with_properties() and - * g_async_initable_init_async() instead. See #GParameter for more information. - */ - - -/** - * g_async_result_get_source_object: - * @res: a #GAsyncResult - * - * Gets the source object from a #GAsyncResult. - * - * Returns: (transfer full) (nullable): a new reference to the source - * object for the @res, or %NULL if there is none. - */ - - -/** - * g_async_result_get_user_data: - * @res: a #GAsyncResult. - * - * Gets the user data from a #GAsyncResult. - * - * Returns: (transfer full): the user data for @res. - */ - - -/** - * g_async_result_is_tagged: - * @res: a #GAsyncResult - * @source_tag: an application-defined tag - * - * Checks if @res has the given @source_tag (generally a function - * pointer indicating the function @res was created by). - * - * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if - * not. - * Since: 2.34 - */ - - -/** - * g_async_result_legacy_propagate_error: - * @res: a #GAsyncResult - * @error: (out): a location to propagate the error to. - * - * If @res is a #GSimpleAsyncResult, this is equivalent to - * g_simple_async_result_propagate_error(). Otherwise it returns - * %FALSE. - * - * This can be used for legacy error handling in async *_finish() - * wrapper functions that traditionally handled #GSimpleAsyncResult - * error returns themselves rather than calling into the virtual method. - * This should not be used in new code; #GAsyncResult errors that are - * set by virtual methods should also be extracted by virtual methods, - * to enable subclasses to chain up correctly. - * - * Returns: %TRUE if @error is has been filled in with an error from - * @res, %FALSE if not. - * Since: 2.34 - */ - - -/** - * g_buffered_input_stream_fill: - * @stream: a #GBufferedInputStream - * @count: the number of bytes that will be read from the stream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to read @count bytes from the stream into the buffer. - * Will block during this read. - * - * If @count is zero, returns zero and does nothing. A value of @count - * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the number of bytes read into the buffer is returned. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. near the end of a file. Zero is returned on end of file - * (or if @count is zero), but never otherwise. - * - * If @count is -1 then the attempted read size is equal to the number of - * bytes that are required to fill the buffer. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * - * On error -1 is returned and @error is set accordingly. - * - * For the asynchronous, non-blocking, version of this function, see - * g_buffered_input_stream_fill_async(). - * - * Returns: the number of bytes read into @stream's buffer, up to @count, - * or -1 on error. - */ - - -/** - * g_buffered_input_stream_fill_async: - * @stream: a #GBufferedInputStream - * @count: the number of bytes that will be read from the stream - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): a #gpointer - * - * Reads data into @stream's buffer asynchronously, up to @count size. - * @io_priority can be used to prioritize reads. For the synchronous - * version of this function, see g_buffered_input_stream_fill(). - * - * If @count is -1 then the attempted read size is equal to the number - * of bytes that are required to fill the buffer. - */ - - -/** - * g_buffered_input_stream_fill_finish: - * @stream: a #GBufferedInputStream - * @result: a #GAsyncResult - * @error: a #GError - * - * Finishes an asynchronous read. - * - * Returns: a #gssize of the read stream, or `-1` on an error. - */ - - -/** - * g_buffered_input_stream_get_available: - * @stream: #GBufferedInputStream - * - * Gets the size of the available data within the stream. - * - * Returns: size of the available stream. - */ - - -/** - * g_buffered_input_stream_get_buffer_size: - * @stream: a #GBufferedInputStream - * - * Gets the size of the input buffer. - * - * Returns: the current buffer size. - */ - - -/** - * g_buffered_input_stream_new: - * @base_stream: a #GInputStream - * - * Creates a new #GInputStream from the given @base_stream, with - * a buffer set to the default size (4 kilobytes). - * - * Returns: a #GInputStream for the given @base_stream. - */ - - -/** - * g_buffered_input_stream_new_sized: - * @base_stream: a #GInputStream - * @size: a #gsize - * - * Creates a new #GBufferedInputStream from the given @base_stream, - * with a buffer set to @size. - * - * Returns: a #GInputStream. - */ - - -/** - * g_buffered_input_stream_peek: - * @stream: a #GBufferedInputStream - * @buffer: (array length=count) (element-type guint8): a pointer to - * an allocated chunk of memory - * @offset: a #gsize - * @count: a #gsize - * - * Peeks in the buffer, copying data of size @count into @buffer, - * offset @offset bytes. - * - * Returns: a #gsize of the number of bytes peeked, or -1 on error. - */ - - -/** - * g_buffered_input_stream_peek_buffer: - * @stream: a #GBufferedInputStream - * @count: (out): a #gsize to get the number of bytes available in the buffer - * - * Returns the buffer with the currently available bytes. The returned - * buffer must not be modified and will become invalid when reading from - * the stream or filling the buffer. - * - * Returns: (array length=count) (element-type guint8) (transfer none): - * read-only buffer - */ - - -/** - * g_buffered_input_stream_read_byte: - * @stream: a #GBufferedInputStream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to read a single byte from the stream or the buffer. Will block - * during this read. - * - * On success, the byte read from the stream is returned. On end of stream - * -1 is returned but it's not an exceptional error and @error is not set. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * - * On error -1 is returned and @error is set accordingly. - * - * Returns: the byte read from the @stream, or -1 on end of stream or error. - */ - - -/** - * g_buffered_input_stream_set_buffer_size: - * @stream: a #GBufferedInputStream - * @size: a #gsize - * - * Sets the size of the internal buffer of @stream to @size, or to the - * size of the contents of the buffer. The buffer can never be resized - * smaller than its current contents. - */ - - -/** - * g_buffered_output_stream_get_auto_grow: - * @stream: a #GBufferedOutputStream. - * - * Checks if the buffer automatically grows as data is added. - * - * Returns: %TRUE if the @stream's buffer automatically grows, - * %FALSE otherwise. - */ - - -/** - * g_buffered_output_stream_get_buffer_size: - * @stream: a #GBufferedOutputStream. - * - * Gets the size of the buffer in the @stream. - * - * Returns: the current size of the buffer. - */ - - -/** - * g_buffered_output_stream_new: - * @base_stream: a #GOutputStream. - * - * Creates a new buffered output stream for a base stream. - * - * Returns: a #GOutputStream for the given @base_stream. - */ - - -/** - * g_buffered_output_stream_new_sized: - * @base_stream: a #GOutputStream. - * @size: a #gsize. - * - * Creates a new buffered output stream with a given buffer size. - * - * Returns: a #GOutputStream with an internal buffer set to @size. - */ - - -/** - * g_buffered_output_stream_set_auto_grow: - * @stream: a #GBufferedOutputStream. - * @auto_grow: a #gboolean. - * - * Sets whether or not the @stream's buffer should automatically grow. - * If @auto_grow is true, then each write will just make the buffer - * larger, and you must manually flush the buffer to actually write out - * the data to the underlying stream. - */ - - -/** - * g_buffered_output_stream_set_buffer_size: - * @stream: a #GBufferedOutputStream. - * @size: a #gsize. - * - * Sets the size of the internal buffer to @size. - */ - - -/** - * g_bus_get: - * @bus_type: a #GBusType - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to @callback - * - * Asynchronously connects to the message bus specified by @bus_type. - * - * When the operation is finished, @callback will be invoked. You can - * then call g_bus_get_finish() to get the result of the operation. - * - * This is an asynchronous failable function. See g_bus_get_sync() for - * the synchronous version. - * - * Since: 2.26 - */ - - -/** - * g_bus_get_finish: - * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed - * to g_bus_get() - * @error: return location for error or %NULL - * - * Finishes an operation started with g_bus_get(). - * - * The returned object is a singleton, that is, shared with other - * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the - * event that you need a private message bus connection, use - * g_dbus_address_get_for_bus_sync() and - * g_dbus_connection_new_for_address(). - * - * Note that the returned #GDBusConnection object will (usually) have - * the #GDBusConnection:exit-on-close property set to %TRUE. - * - * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. - * Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_bus_get_sync: - * @bus_type: a #GBusType - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL - * - * Synchronously connects to the message bus specified by @bus_type. - * Note that the returned object may shared with other callers, - * e.g. if two separate parts of a process calls this function with - * the same @bus_type, they will share the same object. - * - * This is a synchronous failable function. See g_bus_get() and - * g_bus_get_finish() for the asynchronous version. - * - * The returned object is a singleton, that is, shared with other - * callers of g_bus_get() and g_bus_get_sync() for @bus_type. In the - * event that you need a private message bus connection, use - * g_dbus_address_get_for_bus_sync() and - * g_dbus_connection_new_for_address(). - * - * Note that the returned #GDBusConnection object will (usually) have - * the #GDBusConnection:exit-on-close property set to %TRUE. - * - * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. - * Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_bus_own_name: - * @bus_type: the type of bus to own a name on - * @name: the well-known name to own - * @flags: a set of flags from the #GBusNameOwnerFlags enumeration - * @bus_acquired_handler: (nullable): handler to invoke when connected to the bus of type @bus_type or %NULL - * @name_acquired_handler: (nullable): handler to invoke when @name is acquired or %NULL - * @name_lost_handler: (nullable): handler to invoke when @name is lost or %NULL - * @user_data: user data to pass to handlers - * @user_data_free_func: (nullable): function for freeing @user_data or %NULL - * - * Starts acquiring @name on the bus specified by @bus_type and calls - * @name_acquired_handler and @name_lost_handler when the name is - * acquired respectively lost. Callbacks will be invoked in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this function from. - * - * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler - * callbacks will be invoked after calling this function - there are three - * possible cases: - * - * - @name_lost_handler with a %NULL connection (if a connection to the bus - * can't be made). - * - * - @bus_acquired_handler then @name_lost_handler (if the name can't be - * obtained) - * - * - @bus_acquired_handler then @name_acquired_handler (if the name was - * obtained). - * - * When you are done owning the name, just call g_bus_unown_name() - * with the owner id this function returns. - * - * If the name is acquired or lost (for example another application - * could acquire the name if you allow replacement or the application - * currently owning the name exits), the handlers are also invoked. - * If the #GDBusConnection that is used for attempting to own the name - * closes, then @name_lost_handler is invoked since it is no longer - * possible for other processes to access the process. - * - * You cannot use g_bus_own_name() several times for the same name (unless - * interleaved with calls to g_bus_unown_name()) - only the first call - * will work. - * - * Another guarantee is that invocations of @name_acquired_handler - * and @name_lost_handler are guaranteed to alternate; that - * is, if @name_acquired_handler is invoked then you are - * guaranteed that the next time one of the handlers is invoked, it - * will be @name_lost_handler. The reverse is also true. - * - * If you plan on exporting objects (using e.g. - * g_dbus_connection_register_object()), note that it is generally too late - * to export the objects in @name_acquired_handler. Instead, you can do this - * in @bus_acquired_handler since you are guaranteed that this will run - * before @name is requested from the bus. - * - * This behavior makes it very simple to write applications that wants - * to [own names][gdbus-owning-names] and export objects. - * Simply register objects to be exported in @bus_acquired_handler and - * unregister the objects (if any) in @name_lost_handler. - * - * Returns: an identifier (never 0) that can be used with - * g_bus_unown_name() to stop owning the name. - * Since: 2.26 - */ - - -/** - * g_bus_own_name_on_connection: - * @connection: a #GDBusConnection - * @name: the well-known name to own - * @flags: a set of flags from the #GBusNameOwnerFlags enumeration - * @name_acquired_handler: (nullable): handler to invoke when @name is acquired or %NULL - * @name_lost_handler: (nullable): handler to invoke when @name is lost or %NULL - * @user_data: user data to pass to handlers - * @user_data_free_func: (nullable): function for freeing @user_data or %NULL - * - * Like g_bus_own_name() but takes a #GDBusConnection instead of a - * #GBusType. - * - * Returns: an identifier (never 0) that can be used with - * g_bus_unown_name() to stop owning the name - * Since: 2.26 - */ - - -/** - * g_bus_own_name_on_connection_with_closures: (rename-to g_bus_own_name_on_connection) - * @connection: a #GDBusConnection - * @name: the well-known name to own - * @flags: a set of flags from the #GBusNameOwnerFlags enumeration - * @name_acquired_closure: (nullable): #GClosure to invoke when @name is - * acquired or %NULL - * @name_lost_closure: (nullable): #GClosure to invoke when @name is lost - * or %NULL - * - * Version of g_bus_own_name_on_connection() using closures instead of - * callbacks for easier binding in other languages. - * - * Returns: an identifier (never 0) that can be used with - * g_bus_unown_name() to stop owning the name. - * Since: 2.26 - */ - - -/** - * g_bus_own_name_with_closures: (rename-to g_bus_own_name) - * @bus_type: the type of bus to own a name on - * @name: the well-known name to own - * @flags: a set of flags from the #GBusNameOwnerFlags enumeration - * @bus_acquired_closure: (nullable): #GClosure to invoke when connected to - * the bus of type @bus_type or %NULL - * @name_acquired_closure: (nullable): #GClosure to invoke when @name is - * acquired or %NULL - * @name_lost_closure: (nullable): #GClosure to invoke when @name is lost or - * %NULL - * - * Version of g_bus_own_name() using closures instead of callbacks for - * easier binding in other languages. - * - * Returns: an identifier (never 0) that can be used with - * g_bus_unown_name() to stop owning the name. - * Since: 2.26 - */ - - -/** - * g_bus_unown_name: - * @owner_id: an identifier obtained from g_bus_own_name() - * - * Stops owning a name. - * - * Note that there may still be D-Bus traffic to process (relating to owning - * and unowning the name) in the current thread-default #GMainContext after - * this function has returned. You should continue to iterate the #GMainContext - * until the #GDestroyNotify function passed to g_bus_own_name() is called, in - * order to avoid memory leaks through callbacks queued on the #GMainContext - * after it’s stopped being iterated. - * - * Since: 2.26 - */ - - -/** - * g_bus_unwatch_name: - * @watcher_id: An identifier obtained from g_bus_watch_name() - * - * Stops watching a name. - * - * Note that there may still be D-Bus traffic to process (relating to watching - * and unwatching the name) in the current thread-default #GMainContext after - * this function has returned. You should continue to iterate the #GMainContext - * until the #GDestroyNotify function passed to g_bus_watch_name() is called, in - * order to avoid memory leaks through callbacks queued on the #GMainContext - * after it’s stopped being iterated. - * - * Since: 2.26 - */ - - -/** - * g_bus_watch_name: - * @bus_type: The type of bus to watch a name on. - * @name: The name (well-known or unique) to watch. - * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_handler: (nullable): Handler to invoke when @name is known to exist or %NULL. - * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL. - * - * Starts watching @name on the bus specified by @bus_type and calls - * @name_appeared_handler and @name_vanished_handler when the name is - * known to have an owner respectively known to lose its - * owner. Callbacks will be invoked in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this function from. - * - * You are guaranteed that one of the handlers will be invoked after - * calling this function. When you are done watching the name, just - * call g_bus_unwatch_name() with the watcher id this function - * returns. - * - * If the name vanishes or appears (for example the application owning - * the name could restart), the handlers are also invoked. If the - * #GDBusConnection that is used for watching the name disconnects, then - * @name_vanished_handler is invoked since it is no longer - * possible to access the name. - * - * Another guarantee is that invocations of @name_appeared_handler - * and @name_vanished_handler are guaranteed to alternate; that - * is, if @name_appeared_handler is invoked then you are - * guaranteed that the next time one of the handlers is invoked, it - * will be @name_vanished_handler. The reverse is also true. - * - * This behavior makes it very simple to write applications that want - * to take action when a certain [name exists][gdbus-watching-names]. - * Basically, the application should create object proxies in - * @name_appeared_handler and destroy them again (if any) in - * @name_vanished_handler. - * - * Returns: An identifier (never 0) that can be used with - * g_bus_unwatch_name() to stop watching the name. - * Since: 2.26 - */ - - -/** - * g_bus_watch_name_on_connection: - * @connection: A #GDBusConnection. - * @name: The name (well-known or unique) to watch. - * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_handler: (nullable): Handler to invoke when @name is known to exist or %NULL. - * @name_vanished_handler: (nullable): Handler to invoke when @name is known to not exist or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: (nullable): Function for freeing @user_data or %NULL. - * - * Like g_bus_watch_name() but takes a #GDBusConnection instead of a - * #GBusType. - * - * Returns: An identifier (never 0) that can be used with - * g_bus_unwatch_name() to stop watching the name. - * Since: 2.26 - */ - - -/** - * g_bus_watch_name_on_connection_with_closures: (rename-to g_bus_watch_name_on_connection) - * @connection: A #GDBusConnection. - * @name: The name (well-known or unique) to watch. - * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_closure: (nullable): #GClosure to invoke when @name is known - * to exist or %NULL. - * @name_vanished_closure: (nullable): #GClosure to invoke when @name is known - * to not exist or %NULL. - * - * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for - * easier binding in other languages. - * - * Returns: An identifier (never 0) that can be used with - * g_bus_unwatch_name() to stop watching the name. - * Since: 2.26 - */ - - -/** - * g_bus_watch_name_with_closures: (rename-to g_bus_watch_name) - * @bus_type: The type of bus to watch a name on. - * @name: The name (well-known or unique) to watch. - * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_closure: (nullable): #GClosure to invoke when @name is known - * to exist or %NULL. - * @name_vanished_closure: (nullable): #GClosure to invoke when @name is known - * to not exist or %NULL. - * - * Version of g_bus_watch_name() using closures instead of callbacks for - * easier binding in other languages. - * - * Returns: An identifier (never 0) that can be used with - * g_bus_unwatch_name() to stop watching the name. - * Since: 2.26 - */ - - -/** - * g_bytes_icon_get_bytes: - * @icon: a #GIcon. - * - * Gets the #GBytes associated with the given @icon. - * - * Returns: (transfer none): a #GBytes. - * Since: 2.38 - */ - - -/** - * g_bytes_icon_new: - * @bytes: a #GBytes. - * - * Creates a new icon for a bytes. - * - * This cannot fail, but loading and interpreting the bytes may fail later on - * (for example, if g_loadable_icon_load() is called) if the image is invalid. - * - * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given - * @bytes. - * Since: 2.38 - */ - - -/** - * g_cancellable_cancel: - * @cancellable: (nullable): a #GCancellable object. - * - * Will set @cancellable to cancelled, and will emit the - * #GCancellable::cancelled signal. (However, see the warning about - * race conditions in the documentation for that signal if you are - * planning to connect to it.) - * - * This function is thread-safe. In other words, you can safely call - * it from a thread other than the one running the operation that was - * passed the @cancellable. - * - * If @cancellable is %NULL, this function returns immediately for convenience. - * - * The convention within GIO is that cancelling an asynchronous - * operation causes it to complete asynchronously. That is, if you - * cancel the operation from the same thread in which it is running, - * then the operation's #GAsyncReadyCallback will not be invoked until - * the application returns to the main loop. - */ - - -/** - * g_cancellable_connect: - * @cancellable: A #GCancellable. - * @callback: The #GCallback to connect. - * @data: Data to pass to @callback. - * @data_destroy_func: (nullable): Free function for @data or %NULL. - * - * Convenience function to connect to the #GCancellable::cancelled - * signal. Also handles the race condition that may happen - * if the cancellable is cancelled right before connecting. - * - * @callback is called at most once, either directly at the - * time of the connect if @cancellable is already cancelled, - * or when @cancellable is cancelled in some thread. - * - * @data_destroy_func will be called when the handler is - * disconnected, or immediately if the cancellable is already - * cancelled. - * - * See #GCancellable::cancelled for details on how to use this. - * - * Since GLib 2.40, the lock protecting @cancellable is not held when - * @callback is invoked. This lifts a restriction in place for - * earlier GLib versions which now makes it easier to write cleanup - * code that unconditionally invokes e.g. g_cancellable_cancel(). - * - * Returns: The id of the signal handler or 0 if @cancellable has already - * been cancelled. - * Since: 2.22 - */ - - -/** - * g_cancellable_disconnect: - * @cancellable: (nullable): A #GCancellable or %NULL. - * @handler_id: Handler id of the handler to be disconnected, or `0`. - * - * Disconnects a handler from a cancellable instance similar to - * g_signal_handler_disconnect(). Additionally, in the event that a - * signal handler is currently running, this call will block until the - * handler has finished. Calling this function from a - * #GCancellable::cancelled signal handler will therefore result in a - * deadlock. - * - * This avoids a race condition where a thread cancels at the - * same time as the cancellable operation is finished and the - * signal handler is removed. See #GCancellable::cancelled for - * details on how to use this. - * - * If @cancellable is %NULL or @handler_id is `0` this function does - * nothing. - * - * Since: 2.22 - */ - - -/** - * g_cancellable_get_current: - * - * Gets the top cancellable from the stack. - * - * Returns: (nullable) (transfer none): a #GCancellable from the top - * of the stack, or %NULL if the stack is empty. - */ - - -/** - * g_cancellable_get_fd: - * @cancellable: a #GCancellable. - * - * Gets the file descriptor for a cancellable job. This can be used to - * implement cancellable operations on Unix systems. The returned fd will - * turn readable when @cancellable is cancelled. - * - * You are not supposed to read from the fd yourself, just check for - * readable status. Reading to unset the readable status is done - * with g_cancellable_reset(). - * - * After a successful return from this function, you should use - * g_cancellable_release_fd() to free up resources allocated for - * the returned file descriptor. - * - * See also g_cancellable_make_pollfd(). - * - * Returns: A valid file descriptor. `-1` if the file descriptor - * is not supported, or on errors. - */ - - -/** - * g_cancellable_is_cancelled: - * @cancellable: (nullable): a #GCancellable or %NULL - * - * Checks if a cancellable job has been cancelled. - * - * Returns: %TRUE if @cancellable is cancelled, - * FALSE if called with %NULL or if item is not cancelled. - */ - - -/** - * g_cancellable_make_pollfd: - * @cancellable: (nullable): a #GCancellable or %NULL - * @pollfd: a pointer to a #GPollFD - * - * Creates a #GPollFD corresponding to @cancellable; this can be passed - * to g_poll() and used to poll for cancellation. This is useful both - * for unix systems without a native poll and for portability to - * windows. - * - * When this function returns %TRUE, you should use - * g_cancellable_release_fd() to free up resources allocated for the - * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd(). - * - * If this function returns %FALSE, either no @cancellable was given or - * resource limits prevent this function from allocating the necessary - * structures for polling. (On Linux, you will likely have reached - * the maximum number of file descriptors.) The suggested way to handle - * these cases is to ignore the @cancellable. - * - * You are not supposed to read from the fd yourself, just check for - * readable status. Reading to unset the readable status is done - * with g_cancellable_reset(). - * - * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on - * failure to prepare the cancellable. - * Since: 2.22 - */ - - -/** - * g_cancellable_new: - * - * Creates a new #GCancellable object. - * - * Applications that want to start one or more operations - * that should be cancellable should create a #GCancellable - * and pass it to the operations. - * - * One #GCancellable can be used in multiple consecutive - * operations or in multiple concurrent operations. - * - * Returns: a #GCancellable. - */ - - -/** - * g_cancellable_pop_current: - * @cancellable: a #GCancellable object - * - * Pops @cancellable off the cancellable stack (verifying that @cancellable - * is on the top of the stack). - */ - - -/** - * g_cancellable_push_current: - * @cancellable: a #GCancellable object - * - * Pushes @cancellable onto the cancellable stack. The current - * cancellable can then be received using g_cancellable_get_current(). - * - * This is useful when implementing cancellable operations in - * code that does not allow you to pass down the cancellable object. - * - * This is typically called automatically by e.g. #GFile operations, - * so you rarely have to call this yourself. - */ - - -/** - * g_cancellable_release_fd: - * @cancellable: a #GCancellable - * - * Releases a resources previously allocated by g_cancellable_get_fd() - * or g_cancellable_make_pollfd(). - * - * For compatibility reasons with older releases, calling this function - * is not strictly required, the resources will be automatically freed - * when the @cancellable is finalized. However, the @cancellable will - * block scarce file descriptors until it is finalized if this function - * is not called. This can cause the application to run out of file - * descriptors when many #GCancellables are used at the same time. - * - * Since: 2.22 - */ - - -/** - * g_cancellable_reset: - * @cancellable: a #GCancellable object. - * - * Resets @cancellable to its uncancelled state. - * - * If cancellable is currently in use by any cancellable operation - * then the behavior of this function is undefined. - * - * Note that it is generally not a good idea to reuse an existing - * cancellable for more operations after it has been cancelled once, - * as this function might tempt you to do. The recommended practice - * is to drop the reference to a cancellable after cancelling it, - * and let it die with the outstanding async operations. You should - * create a fresh cancellable for further async operations. - */ - - -/** - * g_cancellable_set_error_if_cancelled: - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: #GError to append error state to - * - * If the @cancellable is cancelled, sets the error to notify - * that the operation was cancelled. - * - * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not - */ - - -/** - * g_cancellable_source_new: - * @cancellable: (nullable): a #GCancellable, or %NULL - * - * Creates a source that triggers if @cancellable is cancelled and - * calls its callback of type #GCancellableSourceFunc. This is - * primarily useful for attaching to another (non-cancellable) source - * with g_source_add_child_source() to add cancellability to it. - * - * For convenience, you can call this with a %NULL #GCancellable, - * in which case the source will never trigger. - * - * The new #GSource will hold a reference to the #GCancellable. - * - * Returns: (transfer full): the new #GSource. - * Since: 2.28 - */ - - -/** - * g_charset_converter_get_num_fallbacks: - * @converter: a #GCharsetConverter - * - * Gets the number of fallbacks that @converter has applied so far. - * - * Returns: the number of fallbacks that @converter has applied - * Since: 2.24 - */ - - -/** - * g_charset_converter_get_use_fallback: - * @converter: a #GCharsetConverter - * - * Gets the #GCharsetConverter:use-fallback property. - * - * Returns: %TRUE if fallbacks are used by @converter - * Since: 2.24 - */ - - -/** - * g_charset_converter_new: - * @to_charset: destination charset - * @from_charset: source charset - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a new #GCharsetConverter. - * - * Returns: a new #GCharsetConverter or %NULL on error. - * Since: 2.24 - */ - - -/** - * g_charset_converter_set_use_fallback: - * @converter: a #GCharsetConverter - * @use_fallback: %TRUE to use fallbacks - * - * Sets the #GCharsetConverter:use-fallback property. - * - * Since: 2.24 - */ - - -/** - * g_content_type_can_be_executable: - * @type: a content type string - * - * Checks if a content type can be executable. Note that for instance - * things like text files can be executables (i.e. scripts and batch files). - * - * Returns: %TRUE if the file type corresponds to a type that - * can be executable, %FALSE otherwise. - */ - - -/** - * g_content_type_equals: - * @type1: a content type string - * @type2: a content type string - * - * Compares two content types for equality. - * - * Returns: %TRUE if the two strings are identical or equivalent, - * %FALSE otherwise. - */ - - -/** - * g_content_type_from_mime_type: - * @mime_type: a mime type string - * - * Tries to find a content type based on the mime type name. - * - * Returns: (nullable): Newly allocated string with content type or - * %NULL. Free with g_free() - * Since: 2.18 - */ - - -/** - * g_content_type_get_description: - * @type: a content type string - * - * Gets the human readable description of the content type. - * - * Returns: a short description of the content type @type. Free the - * returned string with g_free() - */ - - -/** - * g_content_type_get_generic_icon_name: - * @type: a content type string - * - * Gets the generic icon name for a content type. - * - * See the - * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) - * specification for more on the generic icon name. - * - * Returns: (nullable): the registered generic icon name for the given @type, - * or %NULL if unknown. Free with g_free() - * Since: 2.34 - */ - - -/** - * g_content_type_get_icon: - * @type: a content type string - * - * Gets the icon for a content type. - * - * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned - * object with g_object_unref() - */ - - -/** - * g_content_type_get_mime_dirs: - * - * Get the list of directories which MIME data is loaded from. See - * g_content_type_set_mime_dirs() for details. - * - * Returns: (transfer none) (array zero-terminated=1): %NULL-terminated list of - * directories to load MIME data from, including any `mime/` subdirectory, - * and with the first directory to try listed first - * Since: 2.60 - */ - - -/** - * g_content_type_get_mime_type: - * @type: a content type string - * - * Gets the mime type for the content type, if one is registered. - * - * Returns: (nullable) (transfer full): the registered mime type for the - * given @type, or %NULL if unknown; free with g_free(). - */ - - -/** - * g_content_type_get_symbolic_icon: - * @type: a content type string - * - * Gets the symbolic icon for a content type. - * - * Returns: (transfer full): symbolic #GIcon corresponding to the content type. - * Free the returned object with g_object_unref() - * Since: 2.34 - */ - - -/** - * g_content_type_guess: - * @filename: (nullable): a string, or %NULL - * @data: (nullable) (array length=data_size): a stream of data, or %NULL - * @data_size: the size of @data - * @result_uncertain: (out) (optional): return location for the certainty - * of the result, or %NULL - * - * Guesses the content type based on example data. If the function is - * uncertain, @result_uncertain will be set to %TRUE. Either @filename - * or @data may be %NULL, in which case the guess will be based solely - * on the other argument. - * - * Returns: a string indicating a guessed content type for the - * given data. Free with g_free() - */ - - -/** - * g_content_type_guess_for_tree: - * @root: the root of the tree to guess a type for - * - * Tries to guess the type of the tree with root @root, by - * looking at the files it contains. The result is an array - * of content types, with the best guess coming first. - * - * The types returned all have the form x-content/foo, e.g. - * x-content/audio-cdda (for audio CDs) or x-content/image-dcf - * (for a camera memory card). See the - * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) - * specification for more on x-content types. - * - * This function is useful in the implementation of - * g_mount_guess_content_type(). - * - * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated - * array of zero or more content types. Free with g_strfreev() - * Since: 2.18 - */ - - -/** - * g_content_type_is_a: - * @type: a content type string - * @supertype: a content type string - * - * Determines if @type is a subset of @supertype. - * - * Returns: %TRUE if @type is a kind of @supertype, - * %FALSE otherwise. - */ - - -/** - * g_content_type_is_mime_type: - * @type: a content type string - * @mime_type: a mime type string - * - * Determines if @type is a subset of @mime_type. - * Convenience wrapper around g_content_type_is_a(). - * - * Returns: %TRUE if @type is a kind of @mime_type, - * %FALSE otherwise. - * Since: 2.52 - */ - - -/** - * g_content_type_is_unknown: - * @type: a content type string - * - * Checks if the content type is the generic "unknown" type. - * On UNIX this is the "application/octet-stream" mimetype, - * while on win32 it is "*" and on OSX it is a dynamic type - * or octet-stream. - * - * Returns: %TRUE if the type is the unknown type. - */ - - -/** - * g_content_type_set_mime_dirs: - * @dirs: (array zero-terminated=1) (nullable): %NULL-terminated list of - * directories to load MIME data from, including any `mime/` subdirectory, - * and with the first directory to try listed first - * - * Set the list of directories used by GIO to load the MIME database. - * If @dirs is %NULL, the directories used are the default: - * - * - the `mime` subdirectory of the directory in `$XDG_DATA_HOME` - * - the `mime` subdirectory of every directory in `$XDG_DATA_DIRS` - * - * This function is intended to be used when writing tests that depend on - * information stored in the MIME database, in order to control the data. - * - * Typically, in case your tests use %G_TEST_OPTION_ISOLATE_DIRS, but they - * depend on the system’s MIME database, you should call this function - * with @dirs set to %NULL before calling g_test_init(), for instance: - * - * |[ - * // Load MIME data from the system - * g_content_type_set_mime_dirs (NULL); - * // Isolate the environment - * g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL); - * - * … - * - * return g_test_run (); - * ]| - * - * Since: 2.60 - */ - - -/** - * g_content_types_get_registered: - * - * Gets a list of strings containing all the registered content types - * known to the system. The list and its data should be freed using - * `g_list_free_full (list, g_free)`. - * - * Returns: (element-type utf8) (transfer full): list of the registered - * content types - */ - - -/** - * g_converter_convert: - * @converter: a #GConverter. - * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer - * containing the data to convert. - * @inbuf_size: the number of bytes in @inbuf - * @outbuf: (element-type guint8) (array length=outbuf_size): a buffer to write - * converted data in. - * @outbuf_size: the number of bytes in @outbuf, must be at least one - * @flags: a #GConverterFlags controlling the conversion details - * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success - * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success - * @error: location to store the error occurring, or %NULL to ignore - * - * This is the main operation used when converting data. It is to be called - * multiple times in a loop, and each time it will do some work, i.e. - * producing some output (in @outbuf) or consuming some input (from @inbuf) or - * both. If its not possible to do any work an error is returned. - * - * Note that a single call may not consume all input (or any input at all). - * Also a call may produce output even if given no input, due to state stored - * in the converter producing output. - * - * If any data was either produced or consumed, and then an error happens, then - * only the successful conversion is reported and the error is returned on the - * next call. - * - * A full conversion loop involves calling this method repeatedly, each time - * giving it new input and space output space. When there is no more input - * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set. - * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED - * each time until all data is consumed and all output is produced, then - * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED - * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance - * in a decompression converter where the end of data is detectable from the - * data (and there might even be other data after the end of the compressed data). - * - * When some data has successfully been converted @bytes_read and is set to - * the number of bytes read from @inbuf, and @bytes_written is set to indicate - * how many bytes was written to @outbuf. If there are more data to output - * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then - * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output - * then %G_CONVERTER_FINISHED is returned. - * - * On error %G_CONVERTER_ERROR is returned and @error is set accordingly. - * Some errors need special handling: - * - * %G_IO_ERROR_NO_SPACE is returned if there is not enough space - * to write the resulting converted data, the application should - * call the function again with a larger @outbuf to continue. - * - * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough - * input to fully determine what the conversion should produce, - * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for - * example with an incomplete multibyte sequence when converting text, - * or when a regexp matches up to the end of the input (and may match - * further input). It may also happen when @inbuf_size is zero and - * there is no more data to produce. - * - * When this happens the application should read more input and then - * call the function again. If further input shows that there is no - * more data call the function again with the same data but with - * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion - * to finish as e.g. in the regexp match case (or, to fail again with - * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the - * input is actually partial). - * - * After g_converter_convert() has returned %G_CONVERTER_FINISHED the - * converter object is in an invalid state where its not allowed - * to call g_converter_convert() anymore. At this time you can only - * free the object or call g_converter_reset() to reset it to the - * initial state. - * - * If the flag %G_CONVERTER_FLUSH is set then conversion is modified - * to try to write out all internal state to the output. The application - * has to call the function multiple times with the flag set, and when - * the available input has been consumed and all internal state has - * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if - * really at the end) is returned instead of %G_CONVERTER_CONVERTED. - * This is somewhat similar to what happens at the end of the input stream, - * but done in the middle of the data. - * - * This has different meanings for different conversions. For instance - * in a compression converter it would mean that we flush all the - * compression state into output such that if you uncompress the - * compressed data you get back all the input data. Doing this may - * make the final file larger due to padding though. Another example - * is a regexp conversion, where if you at the end of the flushed data - * have a match, but there is also a potential longer match. In the - * non-flushed case we would ask for more input, but when flushing we - * treat this as the end of input and do the match. - * - * Flushing is not always possible (like if a charset converter flushes - * at a partial multibyte sequence). Converters are supposed to try - * to produce as much output as possible and then return an error - * (typically %G_IO_ERROR_PARTIAL_INPUT). - * - * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error. - * Since: 2.24 - */ - - -/** - * g_converter_input_stream_get_converter: - * @converter_stream: a #GConverterInputStream - * - * Gets the #GConverter that is used by @converter_stream. - * - * Returns: (transfer none): the converter of the converter input stream - * Since: 2.24 - */ - - -/** - * g_converter_input_stream_new: - * @base_stream: a #GInputStream - * @converter: a #GConverter - * - * Creates a new converter input stream for the @base_stream. - * - * Returns: a new #GInputStream. - */ - - -/** - * g_converter_output_stream_get_converter: - * @converter_stream: a #GConverterOutputStream - * - * Gets the #GConverter that is used by @converter_stream. - * - * Returns: (transfer none): the converter of the converter output stream - * Since: 2.24 - */ - - -/** - * g_converter_output_stream_new: - * @base_stream: a #GOutputStream - * @converter: a #GConverter - * - * Creates a new converter output stream for the @base_stream. - * - * Returns: a new #GOutputStream. - */ - - -/** - * g_converter_reset: - * @converter: a #GConverter. - * - * Resets all internal state in the converter, making it behave - * as if it was just created. If the converter has any internal - * state that would produce output then that output is lost. - * - * Since: 2.24 - */ - - -/** - * g_credentials_get_native: (skip) - * @credentials: A #GCredentials. - * @native_type: The type of native credentials to get. - * - * Gets a pointer to native credentials of type @native_type from - * @credentials. - * - * It is a programming error (which will cause a warning to be - * logged) to use this method if there is no #GCredentials support for - * the OS or if @native_type isn't supported by the OS. - * - * Returns: (transfer none) (nullable): The pointer to native credentials or - * %NULL if there is no #GCredentials support for the OS or if @native_type - * isn't supported by the OS. Do not free the returned data, it is owned - * by @credentials. - * Since: 2.26 - */ - - -/** - * 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 (for example this is the case for - * %G_CREDENTIALS_TYPE_APPLE_XUCRED). - * - * 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. - * - * Tries to get the UNIX user 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 user. - * - * Returns: The UNIX user identifier or `-1` if @error is set. - * Since: 2.26 - */ - - -/** - * g_credentials_is_same_user: - * @credentials: A #GCredentials. - * @other_credentials: A #GCredentials. - * @error: Return location for error or %NULL. - * - * Checks if @credentials and @other_credentials is the same user. - * - * This operation can fail if #GCredentials is not supported on the - * the OS. - * - * Returns: %TRUE if @credentials and @other_credentials has the same - * user, %FALSE otherwise or if @error is set. - * Since: 2.26 - */ - - -/** - * g_credentials_new: - * - * Creates a new #GCredentials object with credentials matching the - * the current process. - * - * Returns: (transfer full): A #GCredentials. Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_credentials_set_native: - * @credentials: A #GCredentials. - * @native_type: The type of native credentials to set. - * @native: (not nullable): A pointer to native credentials. - * - * Copies the native credentials of type @native_type from @native - * into @credentials. - * - * It is a programming error (which will cause a warning to be - * logged) to use this method if there is no #GCredentials support for - * the OS or if @native_type isn't supported by the OS. - * - * Since: 2.26 - */ - - -/** - * g_credentials_set_unix_user: - * @credentials: A #GCredentials. - * @uid: The UNIX user identifier to set. - * @error: Return location for error or %NULL. - * - * Tries to set the UNIX user identifier on @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 user. It can also fail if the OS does not allow the - * use of "spoofed" credentials. - * - * Returns: %TRUE if @uid was set, %FALSE if error is set. - * Since: 2.26 - */ - - -/** - * g_credentials_to_string: - * @credentials: A #GCredentials object. - * - * Creates a human-readable textual representation of @credentials - * that can be used in logging and debug messages. The format of the - * returned string may change in future GLib release. - * - * Returns: (transfer full): A string that should be freed with g_free(). - * Since: 2.26 - */ - - -/** - * g_data_input_stream_get_byte_order: - * @stream: a given #GDataInputStream. - * - * Gets the byte order for the data input stream. - * - * Returns: the @stream's current #GDataStreamByteOrder. - */ - - -/** - * g_data_input_stream_get_newline_type: - * @stream: a given #GDataInputStream. - * - * Gets the current newline type for the @stream. - * - * Returns: #GDataStreamNewlineType for the given @stream. - */ - - -/** - * g_data_input_stream_new: - * @base_stream: a #GInputStream. - * - * Creates a new data input stream for the @base_stream. - * - * Returns: a new #GDataInputStream. - */ - - -/** - * g_data_input_stream_read_byte: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads an unsigned 8-bit/1-byte value from @stream. - * - * Returns: an unsigned 8-bit/1-byte value read from the @stream or `0` - * if an error occurred. - */ - - -/** - * g_data_input_stream_read_int16: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads a 16-bit/2-byte value from @stream. - * - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - * - * Returns: a signed 16-bit/2-byte value read from @stream or `0` if - * an error occurred. - */ - - -/** - * g_data_input_stream_read_int32: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads a signed 32-bit/4-byte value from @stream. - * - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: a signed 32-bit/4-byte value read from the @stream or `0` if - * an error occurred. - */ - - -/** - * g_data_input_stream_read_int64: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads a 64-bit/8-byte value from @stream. - * - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: a signed 64-bit/8-byte value read from @stream or `0` if - * an error occurred. - */ - - -/** - * g_data_input_stream_read_line: - * @stream: a given #GDataInputStream. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads a line from the data input stream. Note that no encoding - * checks or conversion is performed; the input is not guaranteed to - * be UTF-8, and may in fact have embedded NUL characters. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8): - * a NUL terminated byte array with the line that was read in - * (without the newlines). Set @length to a #gsize to get the length - * of the read line. On an error, it will return %NULL and @error - * will be set. If there's no content to read, it will still return - * %NULL, but @error won't be set. - */ - - -/** - * g_data_input_stream_read_line_async: - * @stream: a given #GDataInputStream. - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied. - * @user_data: (closure): the data to pass to callback function. - * - * The asynchronous version of g_data_input_stream_read_line(). It is - * an error to have two outstanding calls to this function. - * - * When the operation is finished, @callback will be called. You - * can then call g_data_input_stream_read_line_finish() to get - * the result of the operation. - * - * Since: 2.20 - */ - - -/** - * g_data_input_stream_read_line_finish: - * @stream: a given #GDataInputStream. - * @result: the #GAsyncResult that was provided to the callback. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @error: #GError for error reporting. - * - * Finish an asynchronous call started by - * g_data_input_stream_read_line_async(). Note the warning about - * string encoding in g_data_input_stream_read_line() applies here as - * well. - * - * Returns: (nullable) (transfer full) (array zero-terminated=1) (element-type guint8): - * a NUL-terminated byte array with the line that was read in - * (without the newlines). Set @length to a #gsize to get the length - * of the read line. On an error, it will return %NULL and @error - * will be set. If there's no content to read, it will still return - * %NULL, but @error won't be set. - * Since: 2.20 - */ - - -/** - * g_data_input_stream_read_line_finish_utf8: - * @stream: a given #GDataInputStream. - * @result: the #GAsyncResult that was provided to the callback. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @error: #GError for error reporting. - * - * Finish an asynchronous call started by - * g_data_input_stream_read_line_async(). - * - * Returns: (nullable) (transfer full): a string with the line that - * was read in (without the newlines). Set @length to a #gsize to - * get the length of the read line. On an error, it will return - * %NULL and @error will be set. For UTF-8 conversion errors, the set - * error domain is %G_CONVERT_ERROR. If there's no content to read, - * it will still return %NULL, but @error won't be set. - * Since: 2.30 - */ - - -/** - * g_data_input_stream_read_line_utf8: - * @stream: a given #GDataInputStream. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads a UTF-8 encoded line from the data input stream. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: (nullable) (transfer full): a NUL terminated UTF-8 string - * with the line that was read in (without the newlines). Set - * @length to a #gsize to get the length of the read line. On an - * error, it will return %NULL and @error will be set. For UTF-8 - * conversion errors, the set error domain is %G_CONVERT_ERROR. If - * there's no content to read, it will still return %NULL, but @error - * won't be set. - * Since: 2.30 - */ - - -/** - * g_data_input_stream_read_uint16: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads an unsigned 16-bit/2-byte value from @stream. - * - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - * - * Returns: an unsigned 16-bit/2-byte value read from the @stream or `0` if - * an error occurred. - */ - - -/** - * g_data_input_stream_read_uint32: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads an unsigned 32-bit/4-byte value from @stream. - * - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: an unsigned 32-bit/4-byte value read from the @stream or `0` if - * an error occurred. - */ - - -/** - * g_data_input_stream_read_uint64: - * @stream: a given #GDataInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads an unsigned 64-bit/8-byte value from @stream. - * - * In order to get the correct byte order for this read operation, - * see g_data_input_stream_get_byte_order(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: an unsigned 64-bit/8-byte read from @stream or `0` if - * an error occurred. - */ - - -/** - * g_data_input_stream_read_until: - * @stream: a given #GDataInputStream. - * @stop_chars: characters to terminate the read. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting. - * - * Reads a string from the data input stream, up to the first - * occurrence of any of the stop characters. - * - * Note that, in contrast to g_data_input_stream_read_until_async(), - * this function consumes the stop character that it finds. - * - * Don't use this function in new code. Its functionality is - * inconsistent with g_data_input_stream_read_until_async(). Both - * functions will be marked as deprecated in a future release. Use - * g_data_input_stream_read_upto() instead, but note that that function - * does not consume the stop character. - * - * Returns: (transfer full): a string with the data that was read - * before encountering any of the stop characters. Set @length to - * a #gsize to get the length of the string. This function will - * return %NULL on an error. - * Deprecated: 2.56: Use g_data_input_stream_read_upto() instead, which has more - * consistent behaviour regarding the stop character. - */ - - -/** - * g_data_input_stream_read_until_async: - * @stream: a given #GDataInputStream. - * @stop_chars: characters to terminate the read. - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied. - * @user_data: (closure): the data to pass to callback function. - * - * The asynchronous version of g_data_input_stream_read_until(). - * It is an error to have two outstanding calls to this function. - * - * Note that, in contrast to g_data_input_stream_read_until(), - * this function does not consume the stop character that it finds. You - * must read it for yourself. - * - * When the operation is finished, @callback will be called. You - * can then call g_data_input_stream_read_until_finish() to get - * the result of the operation. - * - * Don't use this function in new code. Its functionality is - * inconsistent with g_data_input_stream_read_until(). Both functions - * will be marked as deprecated in a future release. Use - * g_data_input_stream_read_upto_async() instead. - * - * Since: 2.20 - * Deprecated: 2.56: Use g_data_input_stream_read_upto_async() instead, which - * has more consistent behaviour regarding the stop character. - */ - - -/** - * g_data_input_stream_read_until_finish: - * @stream: a given #GDataInputStream. - * @result: the #GAsyncResult that was provided to the callback. - * @length: (out) (optional): a #gsize to get the length of the data read in. - * @error: #GError for error reporting. - * - * Finish an asynchronous call started by - * g_data_input_stream_read_until_async(). - * - * Since: 2.20 - * Returns: (transfer full): a string with the data that was read - * before encountering any of the stop characters. Set @length to - * a #gsize to get the length of the string. This function will - * return %NULL on an error. - * Deprecated: 2.56: Use g_data_input_stream_read_upto_finish() instead, which - * has more consistent behaviour regarding the stop character. - */ - - -/** - * g_data_input_stream_read_upto: - * @stream: a #GDataInputStream - * @stop_chars: characters to terminate the read - * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is - * nul-terminated - * @length: (out) (optional): a #gsize to get the length of the data read in - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @error: #GError for error reporting - * - * Reads a string from the data input stream, up to the first - * occurrence of any of the stop characters. - * - * In contrast to g_data_input_stream_read_until(), this function - * does not consume the stop character. You have to use - * g_data_input_stream_read_byte() to get it before calling - * g_data_input_stream_read_upto() again. - * - * Note that @stop_chars may contain '\0' if @stop_chars_len is - * specified. - * - * The returned string will always be nul-terminated on success. - * - * Returns: (transfer full): a string with the data that was read - * before encountering any of the stop characters. Set @length to - * a #gsize to get the length of the string. This function will - * return %NULL on an error - * Since: 2.26 - */ - - -/** - * g_data_input_stream_read_upto_async: - * @stream: a #GDataInputStream - * @stop_chars: characters to terminate the read - * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is - * nul-terminated - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * The asynchronous version of g_data_input_stream_read_upto(). - * It is an error to have two outstanding calls to this function. - * - * In contrast to g_data_input_stream_read_until(), this function - * does not consume the stop character. You have to use - * g_data_input_stream_read_byte() to get it before calling - * g_data_input_stream_read_upto() again. - * - * Note that @stop_chars may contain '\0' if @stop_chars_len is - * specified. - * - * When the operation is finished, @callback will be called. You - * can then call g_data_input_stream_read_upto_finish() to get - * the result of the operation. - * - * Since: 2.26 - */ - - -/** - * g_data_input_stream_read_upto_finish: - * @stream: a #GDataInputStream - * @result: the #GAsyncResult that was provided to the callback - * @length: (out) (optional): a #gsize to get the length of the data read in - * @error: #GError for error reporting - * - * Finish an asynchronous call started by - * g_data_input_stream_read_upto_async(). - * - * Note that this function does not consume the stop character. You - * have to use g_data_input_stream_read_byte() to get it before calling - * g_data_input_stream_read_upto_async() again. - * - * The returned string will always be nul-terminated on success. - * - * Returns: (transfer full): a string with the data that was read - * before encountering any of the stop characters. Set @length to - * a #gsize to get the length of the string. This function will - * return %NULL on an error. - * Since: 2.24 - */ - - -/** - * g_data_input_stream_set_byte_order: - * @stream: a given #GDataInputStream. - * @order: a #GDataStreamByteOrder to set. - * - * This function sets the byte order for the given @stream. All subsequent - * reads from the @stream will be read in the given @order. - */ - - -/** - * g_data_input_stream_set_newline_type: - * @stream: a #GDataInputStream. - * @type: the type of new line return as #GDataStreamNewlineType. - * - * Sets the newline type for the @stream. - * - * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read - * chunk ends in "CR" we must read an additional byte to know if this is "CR" or - * "CR LF", and this might block if there is no more data available. - */ - - -/** - * g_data_output_stream_get_byte_order: - * @stream: a #GDataOutputStream. - * - * Gets the byte order for the stream. - * - * Returns: the #GDataStreamByteOrder for the @stream. - */ - - -/** - * g_data_output_stream_new: - * @base_stream: a #GOutputStream. - * - * Creates a new data output stream for @base_stream. - * - * Returns: #GDataOutputStream. - */ - - -/** - * g_data_output_stream_put_byte: - * @stream: a #GDataOutputStream. - * @data: a #guchar. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Puts a byte into the output stream. - * - * Returns: %TRUE if @data was successfully added to the @stream. - */ - - -/** - * g_data_output_stream_put_int16: - * @stream: a #GDataOutputStream. - * @data: a #gint16. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Puts a signed 16-bit integer into the output stream. - * - * Returns: %TRUE if @data was successfully added to the @stream. - */ - - -/** - * g_data_output_stream_put_int32: - * @stream: a #GDataOutputStream. - * @data: a #gint32. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Puts a signed 32-bit integer into the output stream. - * - * Returns: %TRUE if @data was successfully added to the @stream. - */ - - -/** - * g_data_output_stream_put_int64: - * @stream: a #GDataOutputStream. - * @data: a #gint64. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Puts a signed 64-bit integer into the stream. - * - * Returns: %TRUE if @data was successfully added to the @stream. - */ - - -/** - * g_data_output_stream_put_string: - * @stream: a #GDataOutputStream. - * @str: a string. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Puts a string into the output stream. - * - * Returns: %TRUE if @string was successfully added to the @stream. - */ - - -/** - * g_data_output_stream_put_uint16: - * @stream: a #GDataOutputStream. - * @data: a #guint16. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Puts an unsigned 16-bit integer into the output stream. - * - * Returns: %TRUE if @data was successfully added to the @stream. - */ - - -/** - * g_data_output_stream_put_uint32: - * @stream: a #GDataOutputStream. - * @data: a #guint32. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Puts an unsigned 32-bit integer into the stream. - * - * Returns: %TRUE if @data was successfully added to the @stream. - */ - - -/** - * g_data_output_stream_put_uint64: - * @stream: a #GDataOutputStream. - * @data: a #guint64. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Puts an unsigned 64-bit integer into the stream. - * - * Returns: %TRUE if @data was successfully added to the @stream. - */ - - -/** - * g_data_output_stream_set_byte_order: - * @stream: a #GDataOutputStream. - * @order: a %GDataStreamByteOrder. - * - * Sets the byte order of the data output stream to @order. - */ - - -/** - * g_datagram_based_condition_check: - * @datagram_based: a #GDatagramBased - * @condition: a #GIOCondition mask to check - * - * Checks on the readiness of @datagram_based to perform operations. The - * operations specified in @condition are checked for and masked against the - * currently-satisfied conditions on @datagram_based. The result is returned. - * - * %G_IO_IN will be set in the return value if data is available to read with - * g_datagram_based_receive_messages(), or if the connection is closed remotely - * (EOS); and if the datagram_based has not been closed locally using some - * implementation-specific method (such as g_socket_close() or - * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket). - * - * If the connection is shut down or closed (by calling g_socket_close() or - * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for - * example), all calls to this function will return %G_IO_ERROR_CLOSED. - * - * %G_IO_OUT will be set if it is expected that at least one byte can be sent - * using g_datagram_based_send_messages() without blocking. It will not be set - * if the datagram_based has been closed locally. - * - * %G_IO_HUP will be set if the connection has been closed locally. - * - * %G_IO_ERR will be set if there was an asynchronous error in transmitting data - * previously enqueued using g_datagram_based_send_messages(). - * - * Note that on Windows, it is possible for an operation to return - * %G_IO_ERROR_WOULD_BLOCK even immediately after - * g_datagram_based_condition_check() has claimed that the #GDatagramBased is - * ready for writing. Rather than calling g_datagram_based_condition_check() and - * then writing to the #GDatagramBased if it succeeds, it is generally better to - * simply try writing right away, and try again later if the initial attempt - * returns %G_IO_ERROR_WOULD_BLOCK. - * - * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these - * conditions will always be set in the output if they are true. Apart from - * these flags, the output is guaranteed to be masked by @condition. - * - * This call never blocks. - * - * Returns: the #GIOCondition mask of the current state - * Since: 2.48 - */ - - -/** - * g_datagram_based_condition_wait: - * @datagram_based: a #GDatagramBased - * @condition: a #GIOCondition mask to wait for - * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 - * to block indefinitely - * @cancellable: (nullable): a #GCancellable - * @error: return location for a #GError - * - * Waits for up to @timeout microseconds for condition to become true on - * @datagram_based. If the condition is met, %TRUE is returned. - * - * If @cancellable is cancelled before the condition is met, or if @timeout is - * reached before the condition is met, then %FALSE is returned and @error is - * set appropriately (%G_IO_ERROR_CANCELLED or %G_IO_ERROR_TIMED_OUT). - * - * Returns: %TRUE if the condition was met, %FALSE otherwise - * Since: 2.48 - */ - - -/** - * g_datagram_based_create_source: - * @datagram_based: a #GDatagramBased - * @condition: a #GIOCondition mask to monitor - * @cancellable: (nullable): a #GCancellable - * - * Creates a #GSource that can be attached to a #GMainContext to monitor for - * the availability of the specified @condition on the #GDatagramBased. The - * #GSource keeps a reference to the @datagram_based. - * - * The callback on the source is of the #GDatagramBasedSourceFunc type. - * - * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; these - * conditions will always be reported in the callback if they are true. - * - * If non-%NULL, @cancellable can be used to cancel the source, which will - * cause the source to trigger, reporting the current condition (which is - * likely 0 unless cancellation happened at the same time as a condition - * change). You can check for this in the callback using - * g_cancellable_is_cancelled(). - * - * Returns: (transfer full): a newly allocated #GSource - * Since: 2.48 - */ - - -/** - * g_datagram_based_receive_messages: - * @datagram_based: a #GDatagramBased - * @messages: (array length=num_messages): an array of #GInputMessage structs - * @num_messages: the number of elements in @messages - * @flags: an int containing #GSocketMsgFlags flags for the overall operation - * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 - * to block indefinitely - * @cancellable: (nullable): a %GCancellable - * @error: return location for a #GError - * - * Receive one or more data messages from @datagram_based in one go. - * - * @messages must point to an array of #GInputMessage structs and - * @num_messages must be the length of this array. Each #GInputMessage - * contains a pointer to an array of #GInputVector structs describing the - * buffers that the data received in each message will be written to. - * - * @flags modify how all messages are received. The commonly available - * arguments for this are available in the #GSocketMsgFlags enum, but the - * values there are the same as the system values, and the flags - * are passed in as-is, so you can pass in system-specific flags too. These - * flags affect the overall receive operation. Flags affecting individual - * messages are returned in #GInputMessage.flags. - * - * The other members of #GInputMessage are treated as described in its - * documentation. - * - * If @timeout is negative the call will block until @num_messages have been - * received, the connection is closed remotely (EOS), @cancellable is cancelled, - * or an error occurs. - * - * If @timeout is 0 the call will return up to @num_messages without blocking, - * or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system - * to be received. - * - * If @timeout is positive the call will block on the same conditions as if - * @timeout were negative. If the timeout is reached - * before any messages are received, %G_IO_ERROR_TIMED_OUT is returned, - * otherwise it will return the number of messages received before timing out. - * (Note: This is effectively the behaviour of `MSG_WAITFORONE` with - * recvmmsg().) - * - * To be notified when messages are available, wait for the %G_IO_IN condition. - * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from - * g_datagram_based_receive_messages() even if you were previously notified of a - * %G_IO_IN condition. - * - * If the remote peer closes the connection, any messages queued in the - * underlying receive buffer will be returned, and subsequent calls to - * g_datagram_based_receive_messages() will return 0 (with no error set). - * - * If the connection is shut down or closed (by calling g_socket_close() or - * g_socket_shutdown() with @shutdown_read set, if it’s a #GSocket, for - * example), all calls to this function will return %G_IO_ERROR_CLOSED. - * - * On error -1 is returned and @error is set accordingly. An error will only - * be returned if zero messages could be received; otherwise the number of - * messages successfully received before the error will be returned. If - * @cancellable is cancelled, %G_IO_ERROR_CANCELLED is returned as with any - * other error. - * - * Returns: number of messages received, or -1 on error. Note that the number - * of messages received may be smaller than @num_messages if @timeout is - * zero or positive, if the peer closed the connection, or if @num_messages - * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try - * to receive the remaining messages. - * Since: 2.48 - */ - - -/** - * g_datagram_based_send_messages: - * @datagram_based: a #GDatagramBased - * @messages: (array length=num_messages): an array of #GOutputMessage structs - * @num_messages: the number of elements in @messages - * @flags: an int containing #GSocketMsgFlags flags - * @timeout: the maximum time (in microseconds) to wait, 0 to not block, or -1 - * to block indefinitely - * @cancellable: (nullable): a %GCancellable - * @error: return location for a #GError - * - * Send one or more data messages from @datagram_based in one go. - * - * @messages must point to an array of #GOutputMessage structs and - * @num_messages must be the length of this array. Each #GOutputMessage - * contains an address to send the data to, and a pointer to an array of - * #GOutputVector structs to describe the buffers that the data to be sent - * for each message will be gathered from. - * - * @flags modify how the message is sent. The commonly available arguments - * for this are available in the #GSocketMsgFlags enum, but the - * values there are the same as the system values, and the flags - * are passed in as-is, so you can pass in system-specific flags too. - * - * The other members of #GOutputMessage are treated as described in its - * documentation. - * - * If @timeout is negative the call will block until @num_messages have been - * sent, @cancellable is cancelled, or an error occurs. - * - * If @timeout is 0 the call will send up to @num_messages without blocking, - * or will return %G_IO_ERROR_WOULD_BLOCK if there is no space to send messages. - * - * If @timeout is positive the call will block on the same conditions as if - * @timeout were negative. If the timeout is reached before any messages are - * sent, %G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number - * of messages sent before timing out. - * - * To be notified when messages can be sent, wait for the %G_IO_OUT condition. - * Note though that you may still receive %G_IO_ERROR_WOULD_BLOCK from - * g_datagram_based_send_messages() even if you were previously notified of a - * %G_IO_OUT condition. (On Windows in particular, this is very common due to - * the way the underlying APIs work.) - * - * If the connection is shut down or closed (by calling g_socket_close() or - * g_socket_shutdown() with @shutdown_write set, if it’s a #GSocket, for - * example), all calls to this function will return %G_IO_ERROR_CLOSED. - * - * On error -1 is returned and @error is set accordingly. An error will only - * be returned if zero messages could be sent; otherwise the number of messages - * successfully sent before the error will be returned. If @cancellable is - * cancelled, %G_IO_ERROR_CANCELLED is returned as with any other error. - * - * Returns: number of messages sent, or -1 on error. Note that the number of - * messages sent may be smaller than @num_messages if @timeout is zero - * or positive, or if @num_messages was larger than `UIO_MAXIOV` (1024), in - * which case the caller may re-try to send the remaining messages. - * Since: 2.48 - */ - - -/** - * g_dbus_action_group_get: - * @connection: A #GDBusConnection - * @bus_name: (nullable): the bus name which exports the action - * group or %NULL if @connection is not a message bus connection - * @object_path: the object path at which the action group is exported - * - * Obtains a #GDBusActionGroup for the action group which is exported at - * the given @bus_name and @object_path. - * - * The thread default main context is taken at the time of this call. - * All signals on the menu model (and any linked models) are reported - * with respect to this context. All calls on the returned menu model - * (and linked models) must also originate from this same context, with - * the thread default main context unchanged. - * - * This call is non-blocking. The returned action group may or may not - * already be filled in. The correct thing to do is connect the signals - * for the action group to monitor for changes and then to call - * g_action_group_list_actions() to get the initial list. - * - * Returns: (transfer full): a #GDBusActionGroup - * Since: 2.32 - */ - - -/** - * 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 `/run/bus-for-:0`, - * this function would return `/run/bus-for-%3A0`, - * which could be used in a D-Bus address like - * `unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`. - * - * 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: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL - * - * Synchronously looks up the D-Bus address for the well-known message - * bus instance specified by @bus_type. This may involve using various - * platform specific mechanisms. - * - * The returned address will be in the - * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - * - * Returns: (transfer full): a valid D-Bus address string for @bus_type or - * %NULL if @error is set - * Since: 2.26 - */ - - -/** - * g_dbus_address_get_stream: - * @address: A valid D-Bus address. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: Data to pass to @callback. - * - * Asynchronously connects to an endpoint specified by @address and - * sets up the connection so it is in a state to run the client-side - * of the D-Bus authentication conversation. @address must be in the - * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - * - * When the operation is finished, @callback will be invoked. You can - * then call g_dbus_address_get_stream_finish() to get the result of - * the operation. - * - * This is an asynchronous failable function. See - * g_dbus_address_get_stream_sync() for the synchronous version. - * - * Since: 2.26 - */ - - -/** - * g_dbus_address_get_stream_finish: - * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream(). - * @out_guid: (optional) (out) (nullable): %NULL or return location to store the GUID extracted from @address, if any. - * @error: Return location for error or %NULL. - * - * Finishes an operation started with g_dbus_address_get_stream(). - * - * A server is not required to set a GUID, so @out_guid may be set to %NULL - * even on success. - * - * Returns: (transfer full): A #GIOStream or %NULL if @error is set. - * Since: 2.26 - */ - - -/** - * g_dbus_address_get_stream_sync: - * @address: A valid D-Bus address. - * @out_guid: (optional) (out) (nullable): %NULL or return location to store the GUID extracted from @address, if any. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Synchronously connects to an endpoint specified by @address and - * sets up the connection so it is in a state to run the client-side - * of the D-Bus authentication conversation. @address must be in the - * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - * - * A server is not required to set a GUID, so @out_guid may be set to %NULL - * even on success. - * - * This is a synchronous failable function. See - * g_dbus_address_get_stream() for the asynchronous version. - * - * Returns: (transfer full): A #GIOStream or %NULL if @error is set. - * Since: 2.26 - */ - - -/** - * g_dbus_annotation_info_lookup: - * @annotations: (array zero-terminated=1) (nullable): A %NULL-terminated array of annotations or %NULL. - * @name: The name of the annotation to look up. - * - * Looks up the value of an annotation. - * - * The cost of this function is O(n) in number of annotations. - * - * Returns: (nullable): The value or %NULL if not found. Do not free, it is owned by @annotations. - * Since: 2.26 - */ - - -/** - * g_dbus_annotation_info_ref: - * @info: A #GDBusNodeInfo - * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. - * - * Returns: (not nullable): The same @info. - * Since: 2.26 - */ - - -/** - * g_dbus_annotation_info_unref: - * @info: A #GDBusAnnotationInfo. - * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. - * - * Since: 2.26 - */ - - -/** - * g_dbus_arg_info_ref: - * @info: A #GDBusArgInfo - * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. - * - * Returns: (not nullable): The same @info. - * Since: 2.26 - */ - - -/** - * g_dbus_arg_info_unref: - * @info: A #GDBusArgInfo. - * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. - * - * Since: 2.26 - */ - - -/** - * g_dbus_auth_observer_allow_mechanism: - * @observer: A #GDBusAuthObserver. - * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. - * - * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer. - * - * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not. - * Since: 2.34 - */ - - -/** - * g_dbus_auth_observer_authorize_authenticated_peer: - * @observer: A #GDBusAuthObserver. - * @stream: A #GIOStream for the #GDBusConnection. - * @credentials: (nullable): Credentials received from the peer or %NULL. - * - * Emits the #GDBusAuthObserver::authorize-authenticated-peer signal on @observer. - * - * Returns: %TRUE if the peer is authorized, %FALSE if not. - * Since: 2.26 - */ - - -/** - * g_dbus_auth_observer_new: - * - * Creates a new #GDBusAuthObserver object. - * - * Returns: A #GDBusAuthObserver. Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_connection_add_filter: - * @connection: a #GDBusConnection - * @filter_function: a filter function - * @user_data: user data to pass to @filter_function - * @user_data_free_func: function to free @user_data with when filter - * is removed or %NULL - * - * Adds a message filter. Filters are handlers that are run on all - * incoming and outgoing messages, prior to standard dispatch. Filters - * are run in the order that they were added. The same handler can be - * added as a filter more than once, in which case it will be run more - * than once. Filters added during a filter callback won't be run on - * the message being processed. Filter functions are allowed to modify - * and even drop messages. - * - * Note that filters are run in a dedicated message handling thread so - * they can't block and, generally, can't do anything but signal a - * worker thread. Also note that filters are rarely needed - use API - * such as g_dbus_connection_send_message_with_reply(), - * g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead. - * - * If a filter consumes an incoming message the message is not - * dispatched anywhere else - not even the standard dispatch machinery - * (that API such as g_dbus_connection_signal_subscribe() and - * g_dbus_connection_send_message_with_reply() relies on) will see the - * message. Similarly, if a filter consumes an outgoing message, the - * message will not be sent to the other peer. - * - * If @user_data_free_func is non-%NULL, it will be called (in the - * thread-default main context of the thread you are calling this - * method from) at some point after @user_data is no longer - * needed. (It is not guaranteed to be called synchronously when the - * filter is removed, and may be called after @connection has been - * destroyed.) - * - * Returns: a filter identifier that can be used with - * g_dbus_connection_remove_filter() - * Since: 2.26 - */ - - -/** - * g_dbus_connection_call: - * @connection: a #GDBusConnection - * @bus_name: (nullable): a unique or well-known bus name or %NULL if - * @connection is not a message bus connection - * @object_path: path of remote object - * @interface_name: D-Bus interface to invoke method on - * @method_name: the name of the method to invoke - * @parameters: (nullable): a #GVariant tuple with parameters for the method - * or %NULL if not passing parameters - * @reply_type: (nullable): the expected type of the reply (which will be a - * tuple), or %NULL - * @flags: flags from the #GDBusCallFlags enumeration - * @timeout_msec: the timeout in milliseconds, -1 to use the default - * timeout or %G_MAXINT for no timeout - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: (nullable): a #GAsyncReadyCallback to call when the request - * is satisfied or %NULL if you don't care about the result of the - * method invocation - * @user_data: the data to pass to @callback - * - * Asynchronously invokes the @method_name method on the - * @interface_name D-Bus interface on the remote object at - * @object_path owned by @bus_name. - * - * If @connection is closed then the operation will fail with - * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will - * fail with %G_IO_ERROR_CANCELLED. If @parameters contains a value - * not compatible with the D-Bus protocol, the operation fails with - * %G_IO_ERROR_INVALID_ARGUMENT. - * - * If @reply_type is non-%NULL then the reply will be checked for having this type and an - * error will be raised if it does not match. Said another way, if you give a @reply_type - * then any non-%NULL return value will be of this type. Unless it’s - * %G_VARIANT_TYPE_UNIT, the @reply_type will be a tuple containing one or more - * values. - * - * If the @parameters #GVariant is floating, it is consumed. This allows - * convenient 'inline' use of g_variant_new(), e.g.: - * |[ - * g_dbus_connection_call (connection, - * "org.freedesktop.StringThings", - * "/org/freedesktop/StringThings", - * "org.freedesktop.StringThings", - * "TwoStrings", - * g_variant_new ("(ss)", - * "Thing One", - * "Thing Two"), - * NULL, - * G_DBUS_CALL_FLAGS_NONE, - * -1, - * NULL, - * (GAsyncReadyCallback) two_strings_done, - * NULL); - * ]| - * - * This is an asynchronous method. When the operation is finished, - * @callback will be invoked in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this method from. You can then call - * g_dbus_connection_call_finish() to get the result of the operation. - * See g_dbus_connection_call_sync() for the synchronous version of this - * function. - * - * If @callback is %NULL then the D-Bus method call message will be sent with - * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. - * - * Since: 2.26 - */ - - -/** - * g_dbus_connection_call_finish: - * @connection: a #GDBusConnection - * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call() - * @error: return location for error or %NULL - * - * Finishes an operation started with g_dbus_connection_call(). - * - * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating - * #GVariant tuple with return values. Free with g_variant_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_connection_call_sync: - * @connection: a #GDBusConnection - * @bus_name: (nullable): a unique or well-known bus name or %NULL if - * @connection is not a message bus connection - * @object_path: path of remote object - * @interface_name: D-Bus interface to invoke method on - * @method_name: the name of the method to invoke - * @parameters: (nullable): a #GVariant tuple with parameters for the method - * or %NULL if not passing parameters - * @reply_type: (nullable): the expected type of the reply, or %NULL - * @flags: flags from the #GDBusCallFlags enumeration - * @timeout_msec: the timeout in milliseconds, -1 to use the default - * timeout or %G_MAXINT for no timeout - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL - * - * Synchronously invokes the @method_name method on the - * @interface_name D-Bus interface on the remote object at - * @object_path owned by @bus_name. - * - * If @connection is closed then the operation will fail with - * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the - * operation will fail with %G_IO_ERROR_CANCELLED. If @parameters - * contains a value not compatible with the D-Bus protocol, the operation - * fails with %G_IO_ERROR_INVALID_ARGUMENT. - * - * If @reply_type is non-%NULL then the reply will be checked for having - * this type and an error will be raised if it does not match. Said - * another way, if you give a @reply_type then any non-%NULL return - * value will be of this type. - * - * If the @parameters #GVariant is floating, it is consumed. - * This allows convenient 'inline' use of g_variant_new(), e.g.: - * |[ - * g_dbus_connection_call_sync (connection, - * "org.freedesktop.StringThings", - * "/org/freedesktop/StringThings", - * "org.freedesktop.StringThings", - * "TwoStrings", - * g_variant_new ("(ss)", - * "Thing One", - * "Thing Two"), - * NULL, - * G_DBUS_CALL_FLAGS_NONE, - * -1, - * NULL, - * &error); - * ]| - * - * The calling thread is blocked until a reply is received. See - * g_dbus_connection_call() for the asynchronous version of - * this method. - * - * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating - * #GVariant tuple with return values. Free with g_variant_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_connection_call_with_unix_fd_list: - * @connection: a #GDBusConnection - * @bus_name: (nullable): a unique or well-known bus name or %NULL if - * @connection is not a message bus connection - * @object_path: path of remote object - * @interface_name: D-Bus interface to invoke method on - * @method_name: the name of the method to invoke - * @parameters: (nullable): a #GVariant tuple with parameters for the method - * or %NULL if not passing parameters - * @reply_type: (nullable): the expected type of the reply, or %NULL - * @flags: flags from the #GDBusCallFlags enumeration - * @timeout_msec: the timeout in milliseconds, -1 to use the default - * timeout or %G_MAXINT for no timeout - * @fd_list: (nullable): a #GUnixFDList or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: (nullable): a #GAsyncReadyCallback to call when the request is - * satisfied or %NULL if you don't * care about the result of the - * method invocation - * @user_data: The data to pass to @callback. - * - * Like g_dbus_connection_call() but also takes a #GUnixFDList object. - * - * The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE - * values in the body of the message. For example, if a message contains - * two file descriptors, @fd_list would have length 2, and - * `g_variant_new_handle (0)` and `g_variant_new_handle (1)` would appear - * somewhere in the body of the message (not necessarily in that order!) - * to represent the file descriptors at indexes 0 and 1 respectively. - * - * When designing D-Bus APIs that are intended to be interoperable, - * please note that non-GDBus implementations of D-Bus can usually only - * access file descriptors if they are referenced in this way by a - * value of type %G_VARIANT_TYPE_HANDLE in the body of the message. - * - * This method is only available on UNIX. - * - * Since: 2.30 - */ - - -/** - * g_dbus_connection_call_with_unix_fd_list_finish: - * @connection: a #GDBusConnection - * @out_fd_list: (out) (optional): return location for a #GUnixFDList or %NULL - * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to - * g_dbus_connection_call_with_unix_fd_list() - * @error: return location for error or %NULL - * - * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). - * - * The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE - * values in the body of the message. For example, - * if g_variant_get_handle() returns 5, that is intended to be a reference - * to the file descriptor that can be accessed by - * `g_unix_fd_list_get (*out_fd_list, 5, ...)`. - * - * When designing D-Bus APIs that are intended to be interoperable, - * please note that non-GDBus implementations of D-Bus can usually only - * access file descriptors if they are referenced in this way by a - * value of type %G_VARIANT_TYPE_HANDLE in the body of the message. - * - * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating - * #GVariant tuple with return values. Free with g_variant_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_connection_call_with_unix_fd_list_sync: - * @connection: a #GDBusConnection - * @bus_name: (nullable): a unique or well-known bus name or %NULL - * if @connection is not a message bus connection - * @object_path: path of remote object - * @interface_name: D-Bus interface to invoke method on - * @method_name: the name of the method to invoke - * @parameters: (nullable): a #GVariant tuple with parameters for - * the method or %NULL if not passing parameters - * @reply_type: (nullable): the expected type of the reply, or %NULL - * @flags: flags from the #GDBusCallFlags enumeration - * @timeout_msec: the timeout in milliseconds, -1 to use the default - * timeout or %G_MAXINT for no timeout - * @fd_list: (nullable): a #GUnixFDList or %NULL - * @out_fd_list: (out) (optional): return location for a #GUnixFDList or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL - * - * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. - * See g_dbus_connection_call_with_unix_fd_list() and - * g_dbus_connection_call_with_unix_fd_list_finish() for more details. - * - * This method is only available on UNIX. - * - * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating - * #GVariant tuple with return values. Free with g_variant_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_connection_close: - * @connection: a #GDBusConnection - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: (nullable): a #GAsyncReadyCallback to call when the request is - * satisfied or %NULL if you don't care about the result - * @user_data: The data to pass to @callback - * - * Closes @connection. Note that this never causes the process to - * exit (this might only happen if the other end of a shared message - * bus connection disconnects, see #GDBusConnection:exit-on-close). - * - * Once the connection is closed, operations such as sending a message - * will return with the error %G_IO_ERROR_CLOSED. Closing a connection - * will not automatically flush the connection so queued messages may - * be lost. Use g_dbus_connection_flush() if you need such guarantees. - * - * If @connection is already closed, this method fails with - * %G_IO_ERROR_CLOSED. - * - * When @connection has been closed, the #GDBusConnection::closed - * signal is emitted in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread that @connection was constructed in. - * - * This is an asynchronous method. When the operation is finished, - * @callback will be invoked in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this method from. You can - * then call g_dbus_connection_close_finish() to get the result of the - * operation. See g_dbus_connection_close_sync() for the synchronous - * version. - * - * Since: 2.26 - */ - - -/** - * g_dbus_connection_close_finish: - * @connection: a #GDBusConnection - * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed - * to g_dbus_connection_close() - * @error: return location for error or %NULL - * - * Finishes an operation started with g_dbus_connection_close(). - * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set - * Since: 2.26 - */ - - -/** - * g_dbus_connection_close_sync: - * @connection: a #GDBusConnection - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL - * - * Synchronously closes @connection. The calling thread is blocked - * until this is done. See g_dbus_connection_close() for the - * asynchronous version of this method and more details about what it - * does. - * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set - * Since: 2.26 - */ - - -/** - * g_dbus_connection_emit_signal: - * @connection: a #GDBusConnection - * @destination_bus_name: (nullable): the unique bus name for the destination - * for the signal or %NULL to emit to all listeners - * @object_path: path of remote object - * @interface_name: D-Bus interface to emit a signal on - * @signal_name: the name of the signal to emit - * @parameters: (nullable): a #GVariant tuple with parameters for the signal - * or %NULL if not passing parameters - * @error: Return location for error or %NULL - * - * Emits a signal. - * - * If the parameters GVariant is floating, it is consumed. - * - * This can only fail if @parameters is not compatible with the D-Bus protocol - * (%G_IO_ERROR_INVALID_ARGUMENT), or if @connection has been closed - * (%G_IO_ERROR_CLOSED). - * - * Returns: %TRUE unless @error is set - * Since: 2.26 - */ - - -/** - * g_dbus_connection_export_action_group: - * @connection: a #GDBusConnection - * @object_path: a D-Bus object path - * @action_group: a #GActionGroup - * @error: a pointer to a %NULL #GError, or %NULL - * - * Exports @action_group on @connection at @object_path. - * - * The implemented D-Bus API should be considered private. It is - * subject to change in the future. - * - * A given object path can only have one action group exported on it. - * If this constraint is violated, the export will fail and 0 will be - * returned (with @error set accordingly). - * - * You can unexport the action group using - * g_dbus_connection_unexport_action_group() with the return value of - * this function. - * - * The thread default main context is taken at the time of this call. - * All incoming action activations and state change requests are - * reported from this context. Any changes on the action group that - * cause it to emit signals must also come from this same context. - * Since incoming action activations and state change requests are - * rather likely to cause changes on the action group, this effectively - * limits a given action group to being exported from only one main - * context. - * - * Returns: the ID of the export (never zero), or 0 in case of failure - * Since: 2.32 - */ - - -/** - * g_dbus_connection_export_menu_model: - * @connection: a #GDBusConnection - * @object_path: a D-Bus object path - * @menu: a #GMenuModel - * @error: return location for an error, or %NULL - * - * Exports @menu on @connection at @object_path. - * - * The implemented D-Bus API should be considered private. - * It is subject to change in the future. - * - * 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). - * - * You can unexport the menu model using - * g_dbus_connection_unexport_menu_model() with the return value of - * this function. - * - * Returns: the ID of the export (never zero), or 0 in case of failure - * Since: 2.32 - */ - - -/** - * g_dbus_connection_flush: - * @connection: a #GDBusConnection - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: (nullable): a #GAsyncReadyCallback to call when the - * request is satisfied or %NULL if you don't care about the result - * @user_data: The data to pass to @callback - * - * Asynchronously flushes @connection, that is, writes all queued - * outgoing message to the transport and then flushes the transport - * (using g_output_stream_flush_async()). This is useful in programs - * that wants to emit a D-Bus signal and then exit immediately. Without - * flushing the connection, there is no guaranteed that the message has - * been sent to the networking buffers in the OS kernel. - * - * This is an asynchronous method. When the operation is finished, - * @callback will be invoked in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this method from. You can - * then call g_dbus_connection_flush_finish() to get the result of the - * operation. See g_dbus_connection_flush_sync() for the synchronous - * version. - * - * Since: 2.26 - */ - - -/** - * g_dbus_connection_flush_finish: - * @connection: a #GDBusConnection - * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed - * to g_dbus_connection_flush() - * @error: return location for error or %NULL - * - * Finishes an operation started with g_dbus_connection_flush(). - * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set - * Since: 2.26 - */ - - -/** - * g_dbus_connection_flush_sync: - * @connection: a #GDBusConnection - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL - * - * Synchronously flushes @connection. The calling thread is blocked - * until this is done. See g_dbus_connection_flush() for the - * asynchronous version of this method and more details about what it - * does. - * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set - * Since: 2.26 - */ - - -/** - * g_dbus_connection_get_capabilities: - * @connection: a #GDBusConnection - * - * Gets the capabilities negotiated with the remote peer - * - * Returns: zero or more flags from the #GDBusCapabilityFlags enumeration - * Since: 2.26 - */ - - -/** - * g_dbus_connection_get_exit_on_close: - * @connection: a #GDBusConnection - * - * Gets whether the process is terminated when @connection is - * closed by the remote peer. See - * #GDBusConnection:exit-on-close for more details. - * - * Returns: whether the process is terminated when @connection is - * closed by the remote peer - * Since: 2.26 - */ - - -/** - * g_dbus_connection_get_flags: - * @connection: a #GDBusConnection - * - * Gets the flags used to construct this connection - * - * Returns: zero or more flags from the #GDBusConnectionFlags enumeration - * Since: 2.60 - */ - - -/** - * g_dbus_connection_get_guid: - * @connection: a #GDBusConnection - * - * The GUID of the peer performing the role of server when - * authenticating. See #GDBusConnection:guid for more details. - * - * Returns: (not nullable): The GUID. Do not free this string, it is owned by - * @connection. - * Since: 2.26 - */ - - -/** - * g_dbus_connection_get_last_serial: - * @connection: a #GDBusConnection - * - * Retrieves the last serial number assigned to a #GDBusMessage on - * the current thread. This includes messages sent via both low-level - * API such as g_dbus_connection_send_message() as well as - * high-level API such as g_dbus_connection_emit_signal(), - * g_dbus_connection_call() or g_dbus_proxy_call(). - * - * Returns: the last used serial or zero when no message has been sent - * within the current thread - * Since: 2.34 - */ - - -/** - * g_dbus_connection_get_peer_credentials: - * @connection: a #GDBusConnection - * - * Gets the credentials of the authenticated peer. This will always - * return %NULL unless @connection acted as a server - * (e.g. %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed) - * when set up and the client passed credentials as part of the - * authentication process. - * - * In a message bus setup, the message bus is always the server and - * each application is a client. So this method will always return - * %NULL for message bus clients. - * - * Returns: (transfer none) (nullable): a #GCredentials or %NULL if not - * available. Do not free this object, it is owned by @connection. - * Since: 2.26 - */ - - -/** - * g_dbus_connection_get_stream: - * @connection: a #GDBusConnection - * - * Gets the underlying stream used for IO. - * - * While the #GDBusConnection is active, it will interact with this - * stream from a worker thread, so it is not safe to interact with - * the stream directly. - * - * Returns: (transfer none) (not nullable): the stream used for IO - * Since: 2.26 - */ - - -/** - * g_dbus_connection_get_unique_name: - * @connection: a #GDBusConnection - * - * Gets the unique name of @connection as assigned by the message - * bus. This can also be used to figure out if @connection is a - * message bus connection. - * - * Returns: (nullable): the unique name or %NULL if @connection is not a message - * bus connection. Do not free this string, it is owned by - * @connection. - * Since: 2.26 - */ - - -/** - * g_dbus_connection_is_closed: - * @connection: a #GDBusConnection - * - * Gets whether @connection is closed. - * - * Returns: %TRUE if the connection is closed, %FALSE otherwise - * Since: 2.26 - */ - - -/** - * g_dbus_connection_new: - * @stream: a #GIOStream - * @guid: (nullable): the GUID to use if authenticating as a server or %NULL - * @flags: flags describing how to make the connection - * @observer: (nullable): a #GDBusAuthObserver or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to @callback - * - * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages - * with the end represented by @stream. - * - * If @stream is a #GSocketConnection, then the corresponding #GSocket - * will be put into non-blocking mode. - * - * The D-Bus connection will interact with @stream from a worker thread. - * As a result, the caller should not interact with @stream after this - * method has been called, except by calling g_object_unref() on it. - * - * If @observer is not %NULL it may be used to control the - * authentication process. - * - * When the operation is finished, @callback will be invoked. You can - * then call g_dbus_connection_new_finish() to get the result of the - * operation. - * - * This is an asynchronous failable constructor. See - * g_dbus_connection_new_sync() for the synchronous - * version. - * - * Since: 2.26 - */ - - -/** - * g_dbus_connection_new_finish: - * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback - * passed to g_dbus_connection_new(). - * @error: return location for error or %NULL - * - * Finishes an operation started with g_dbus_connection_new(). - * - * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. Free - * with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_connection_new_for_address: - * @address: a D-Bus address - * @flags: flags describing how to make the connection - * @observer: (nullable): a #GDBusAuthObserver or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: the data to pass to @callback - * - * Asynchronously connects and sets up a D-Bus client connection for - * exchanging D-Bus messages with an endpoint specified by @address - * which must be in the - * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - * - * This constructor can only be used to initiate client-side - * connections - use g_dbus_connection_new() if you need to act as the - * server. In particular, @flags cannot contain the - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER, - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags. - * - * When the operation is finished, @callback will be invoked. You can - * then call g_dbus_connection_new_for_address_finish() to get the result of - * the operation. - * - * If @observer is not %NULL it may be used to control the - * authentication process. - * - * This is an asynchronous failable constructor. See - * g_dbus_connection_new_for_address_sync() for the synchronous - * version. - * - * Since: 2.26 - */ - - -/** - * g_dbus_connection_new_for_address_finish: - * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed - * to g_dbus_connection_new() - * @error: return location for error or %NULL - * - * Finishes an operation started with g_dbus_connection_new_for_address(). - * - * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. - * Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_connection_new_for_address_sync: - * @address: a D-Bus address - * @flags: flags describing how to make the connection - * @observer: (nullable): a #GDBusAuthObserver or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL - * - * Synchronously connects and sets up a D-Bus client connection for - * exchanging D-Bus messages with an endpoint specified by @address - * which must be in the - * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - * - * This constructor can only be used to initiate client-side - * connections - use g_dbus_connection_new_sync() if you need to act - * as the server. In particular, @flags cannot contain the - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER, - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or - * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags. - * - * This is a synchronous failable constructor. See - * g_dbus_connection_new_for_address() for the asynchronous version. - * - * If @observer is not %NULL it may be used to control the - * authentication process. - * - * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. - * Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_connection_new_sync: - * @stream: a #GIOStream - * @guid: (nullable): the GUID to use if authenticating as a server or %NULL - * @flags: flags describing how to make the connection - * @observer: (nullable): a #GDBusAuthObserver or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL - * - * Synchronously sets up a D-Bus connection for exchanging D-Bus messages - * with the end represented by @stream. - * - * If @stream is a #GSocketConnection, then the corresponding #GSocket - * will be put into non-blocking mode. - * - * The D-Bus connection will interact with @stream from a worker thread. - * As a result, the caller should not interact with @stream after this - * method has been called, except by calling g_object_unref() on it. - * - * If @observer is not %NULL it may be used to control the - * authentication process. - * - * This is a synchronous failable constructor. See - * g_dbus_connection_new() for the asynchronous version. - * - * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. - * Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_connection_register_object: - * @connection: a #GDBusConnection - * @object_path: the object path to register at - * @interface_info: introspection data for the interface - * @vtable: (nullable): a #GDBusInterfaceVTable to call into or %NULL - * @user_data: (nullable): data to pass to functions in @vtable - * @user_data_free_func: function to call when the object path is unregistered - * @error: return location for error or %NULL - * - * Registers callbacks for exported objects at @object_path with the - * D-Bus interface that is described in @interface_info. - * - * Calls to functions in @vtable (and @user_data_free_func) will happen - * in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this method from. - * - * Note that all #GVariant values passed to functions in @vtable will match - * the signature given in @interface_info - if a remote caller passes - * incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs` - * is returned to the remote caller. - * - * Additionally, if the remote caller attempts to invoke methods or - * access properties not mentioned in @interface_info the - * `org.freedesktop.DBus.Error.UnknownMethod` resp. - * `org.freedesktop.DBus.Error.InvalidArgs` errors - * are returned to the caller. - * - * It is considered a programming error if the - * #GDBusInterfaceGetPropertyFunc function in @vtable returns a - * #GVariant of incorrect type. - * - * If an existing callback is already registered at @object_path and - * @interface_name, then @error is set to #G_IO_ERROR_EXISTS. - * - * GDBus automatically implements the standard D-Bus interfaces - * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable - * and org.freedesktop.Peer, so you don't have to implement those for the - * objects you export. You can implement org.freedesktop.DBus.Properties - * yourself, e.g. to handle getting and setting of properties asynchronously. - * - * Note that the reference count on @interface_info will be - * incremented by 1 (unless allocated statically, e.g. if the - * reference count is -1, see g_dbus_interface_info_ref()) for as long - * as the object is exported. Also note that @vtable will be copied. - * - * See this [server][gdbus-server] for an example of how to use this method. - * - * Returns: 0 if @error is set, otherwise a registration id (never 0) - * that can be used with g_dbus_connection_unregister_object() - * Since: 2.26 - */ - - -/** - * g_dbus_connection_register_object_with_closures: (rename-to g_dbus_connection_register_object) - * @connection: A #GDBusConnection. - * @object_path: The object path to register at. - * @interface_info: Introspection data for the interface. - * @method_call_closure: (nullable): #GClosure for handling incoming method calls. - * @get_property_closure: (nullable): #GClosure for getting a property. - * @set_property_closure: (nullable): #GClosure for setting a property. - * @error: Return location for error or %NULL. - * - * Version of g_dbus_connection_register_object() using closures instead of a - * #GDBusInterfaceVTable for easier binding in other languages. - * - * Returns: 0 if @error is set, otherwise a registration ID (never 0) - * that can be used with g_dbus_connection_unregister_object() . - * Since: 2.46 - */ - - -/** - * g_dbus_connection_register_subtree: - * @connection: a #GDBusConnection - * @object_path: the object path to register the subtree at - * @vtable: a #GDBusSubtreeVTable to enumerate, introspect and - * dispatch nodes in the subtree - * @flags: flags used to fine tune the behavior of the subtree - * @user_data: data to pass to functions in @vtable - * @user_data_free_func: function to call when the subtree is unregistered - * @error: return location for error or %NULL - * - * Registers a whole subtree of dynamic objects. - * - * The @enumerate and @introspection functions in @vtable are used to - * convey, to remote callers, what nodes exist in the subtree rooted - * by @object_path. - * - * When handling remote calls into any node in the subtree, first the - * @enumerate function is used to check if the node exists. If the node exists - * or the #G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is set - * the @introspection function is used to check if the node supports the - * requested method. If so, the @dispatch function is used to determine - * where to dispatch the call. The collected #GDBusInterfaceVTable and - * #gpointer will be used to call into the interface vtable for processing - * the request. - * - * All calls into user-provided code will be invoked in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this method from. - * - * If an existing subtree is already registered at @object_path or - * then @error is set to #G_IO_ERROR_EXISTS. - * - * Note that it is valid to register regular objects (using - * g_dbus_connection_register_object()) in a subtree registered with - * g_dbus_connection_register_subtree() - if so, the subtree handler - * is tried as the last resort. One way to think about a subtree - * handler is to consider it a fallback handler for object paths not - * registered via g_dbus_connection_register_object() or other bindings. - * - * Note that @vtable will be copied so you cannot change it after - * registration. - * - * See this [server][gdbus-subtree-server] for an example of how to use - * this method. - * - * Returns: 0 if @error is set, otherwise a subtree registration ID (never 0) - * that can be used with g_dbus_connection_unregister_subtree() - * Since: 2.26 - */ - - -/** - * g_dbus_connection_remove_filter: - * @connection: a #GDBusConnection - * @filter_id: an identifier obtained from g_dbus_connection_add_filter() - * - * Removes a filter. - * - * Note that since filters run in a different thread, there is a race - * condition where it is possible that the filter will be running even - * after calling g_dbus_connection_remove_filter(), so you cannot just - * free data that the filter might be using. Instead, you should pass - * a #GDestroyNotify to g_dbus_connection_add_filter(), which will be - * called when it is guaranteed that the data is no longer needed. - * - * Since: 2.26 - */ - - -/** - * g_dbus_connection_send_message: - * @connection: a #GDBusConnection - * @message: a #GDBusMessage - * @flags: flags affecting how the message is sent - * @out_serial: (out) (optional): return location for serial number assigned - * to @message when sending it or %NULL - * @error: Return location for error or %NULL - * - * Asynchronously sends @message to the peer represented by @connection. - * - * Unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number - * will be assigned by @connection and set on @message via - * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the - * serial number used will be written to this location prior to - * submitting the message to the underlying transport. While it has a `volatile` - * qualifier, this is a historical artifact and the argument passed to it should - * not be `volatile`. - * - * If @connection is closed then the operation will fail with - * %G_IO_ERROR_CLOSED. If @message is not well-formed, - * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. - * - * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] - * for an example of how to use this low-level API to send and receive - * UNIX file descriptors. - * - * Note that @message must be unlocked, unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. - * - * Returns: %TRUE if the message was well-formed and queued for - * transmission, %FALSE if @error is set - * Since: 2.26 - */ - - -/** - * g_dbus_connection_send_message_with_reply: - * @connection: a #GDBusConnection - * @message: a #GDBusMessage - * @flags: flags affecting how the message is sent - * @timeout_msec: the timeout in milliseconds, -1 to use the default - * timeout or %G_MAXINT for no timeout - * @out_serial: (out) (optional): return location for serial number assigned - * to @message when sending it or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: (nullable): a #GAsyncReadyCallback to call when the request - * is satisfied or %NULL if you don't care about the result - * @user_data: The data to pass to @callback - * - * Asynchronously sends @message to the peer represented by @connection. - * - * Unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number - * will be assigned by @connection and set on @message via - * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the - * serial number used will be written to this location prior to - * submitting the message to the underlying transport. While it has a `volatile` - * qualifier, this is a historical artifact and the argument passed to it should - * not be `volatile`. - * - * If @connection is closed then the operation will fail with - * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will - * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, - * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. - * - * This is an asynchronous method. When the operation is finished, @callback - * will be invoked in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this method from. You can then call - * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation. - * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version. - * - * Note that @message must be unlocked, unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. - * - * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] - * for an example of how to use this low-level API to send and receive - * UNIX file descriptors. - * - * Since: 2.26 - */ - - -/** - * g_dbus_connection_send_message_with_reply_finish: - * @connection: a #GDBusConnection - * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to - * g_dbus_connection_send_message_with_reply() - * @error: teturn location for error or %NULL - * - * Finishes an operation started with g_dbus_connection_send_message_with_reply(). - * - * Note that @error is only set if a local in-process error - * occurred. That is to say that the returned #GDBusMessage object may - * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use - * g_dbus_message_to_gerror() to transcode this to a #GError. - * - * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] - * for an example of how to use this low-level API to send and receive - * UNIX file descriptors. - * - * Returns: (transfer full): a locked #GDBusMessage or %NULL if @error is set - * Since: 2.26 - */ - - -/** - * g_dbus_connection_send_message_with_reply_sync: - * @connection: a #GDBusConnection - * @message: a #GDBusMessage - * @flags: flags affecting how the message is sent. - * @timeout_msec: the timeout in milliseconds, -1 to use the default - * timeout or %G_MAXINT for no timeout - * @out_serial: (out) (optional): return location for serial number - * assigned to @message when sending it or %NULL - * @cancellable: (nullable): a #GCancellable or %NULL - * @error: return location for error or %NULL - * - * Synchronously sends @message to the peer represented by @connection - * and blocks the calling thread until a reply is received or the - * timeout is reached. See g_dbus_connection_send_message_with_reply() - * for the asynchronous version of this method. - * - * Unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number - * will be assigned by @connection and set on @message via - * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the - * serial number used will be written to this location prior to - * submitting the message to the underlying transport. While it has a `volatile` - * qualifier, this is a historical artifact and the argument passed to it should - * not be `volatile`. - * - * If @connection is closed then the operation will fail with - * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will - * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, - * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. - * - * Note that @error is only set if a local in-process error - * occurred. That is to say that the returned #GDBusMessage object may - * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use - * g_dbus_message_to_gerror() to transcode this to a #GError. - * - * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] - * for an example of how to use this low-level API to send and receive - * UNIX file descriptors. - * - * Note that @message must be unlocked, unless @flags contain the - * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. - * - * Returns: (transfer full): a locked #GDBusMessage that is the reply - * to @message or %NULL if @error is set - * Since: 2.26 - */ - - -/** - * g_dbus_connection_set_exit_on_close: - * @connection: a #GDBusConnection - * @exit_on_close: whether the process should be terminated - * when @connection is closed by the remote peer - * - * Sets whether the process should be terminated when @connection is - * closed by the remote peer. See #GDBusConnection:exit-on-close for - * more details. - * - * Note that this function should be used with care. Most modern UNIX - * desktops tie the notion of a user session with the session bus, and expect - * all of a user's applications to quit when their bus connection goes away. - * If you are setting @exit_on_close to %FALSE for the shared session - * bus connection, you should make sure that your application exits - * when the user session ends. - * - * Since: 2.26 - */ - - -/** - * g_dbus_connection_signal_subscribe: - * @connection: a #GDBusConnection - * @sender: (nullable): sender name to match on (unique or well-known name) - * or %NULL to listen from all senders - * @interface_name: (nullable): D-Bus interface name to match on or %NULL to - * match on all interfaces - * @member: (nullable): D-Bus signal name to match on or %NULL to match on - * all signals - * @object_path: (nullable): object path to match on or %NULL to match on - * all object paths - * @arg0: (nullable): contents of first string argument to match on or %NULL - * to match on all kinds of arguments - * @flags: #GDBusSignalFlags describing how arg0 is used in subscribing to the - * signal - * @callback: callback to invoke when there is a signal matching the requested data - * @user_data: user data to pass to @callback - * @user_data_free_func: (nullable): function to free @user_data with when - * subscription is removed or %NULL - * - * Subscribes to signals on @connection and invokes @callback with a whenever - * the signal is received. Note that @callback will be invoked in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this method from. - * - * If @connection is not a message bus connection, @sender must be - * %NULL. - * - * If @sender is a well-known name note that @callback is invoked with - * the unique name for the owner of @sender, not the well-known name - * as one would expect. This is because the message bus rewrites the - * name. As such, to avoid certain race conditions, users should be - * 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. - * - * If @user_data_free_func is non-%NULL, it will be called (in the - * thread-default main context of the thread you are calling this - * method from) at some point after @user_data is no longer - * needed. (It is not guaranteed to be called synchronously when the - * signal is unsubscribed from, and may be called after @connection - * has been destroyed.) - * - * As @callback is potentially invoked in a different thread from where it’s - * emitted, it’s possible for this to happen after - * g_dbus_connection_signal_unsubscribe() has been called in another thread. - * Due to this, @user_data should have a strong reference which is freed with - * @user_data_free_func, rather than pointing to data whose lifecycle is tied - * to the signal subscription. For example, if a #GObject is used to store the - * subscription ID from g_dbus_connection_signal_subscribe(), a strong reference - * to that #GObject must be passed to @user_data, and g_object_unref() passed to - * @user_data_free_func. You are responsible for breaking the resulting - * reference count cycle by explicitly unsubscribing from the signal when - * dropping the last external reference to the #GObject. Alternatively, a weak - * reference may be used. - * - * It is guaranteed that if you unsubscribe from a signal using - * g_dbus_connection_signal_unsubscribe() from the same thread which made the - * corresponding g_dbus_connection_signal_subscribe() call, @callback will not - * be invoked after g_dbus_connection_signal_unsubscribe() returns. - * - * The returned subscription identifier is an opaque value which is guaranteed - * to never be zero. - * - * This function can never fail. - * - * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe() - * Since: 2.26 - */ - - -/** - * g_dbus_connection_signal_unsubscribe: - * @connection: a #GDBusConnection - * @subscription_id: a subscription id obtained from - * g_dbus_connection_signal_subscribe() - * - * Unsubscribes from signals. - * - * Note that there may still be D-Bus traffic to process (relating to this - * signal subscription) in the current thread-default #GMainContext after this - * function has returned. You should continue to iterate the #GMainContext - * until the #GDestroyNotify function passed to - * g_dbus_connection_signal_subscribe() is called, in order to avoid memory - * leaks through callbacks queued on the #GMainContext after it’s stopped being - * iterated. - * Alternatively, any idle source with a priority lower than %G_PRIORITY_DEFAULT - * that was scheduled after unsubscription, also indicates that all resources - * of this subscription are released. - * - * Since: 2.26 - */ - - -/** - * g_dbus_connection_start_message_processing: - * @connection: a #GDBusConnection - * - * If @connection was created with - * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method - * starts processing messages. Does nothing on if @connection wasn't - * created with this flag or if the method has already been called. - * - * Since: 2.26 - */ - - -/** - * g_dbus_connection_unexport_action_group: - * @connection: a #GDBusConnection - * @export_id: the ID from g_dbus_connection_export_action_group() - * - * Reverses the effect of a previous call to - * g_dbus_connection_export_action_group(). - * - * It is an error to call this function with an ID that wasn't returned - * from g_dbus_connection_export_action_group() or to call it with the - * same ID more than once. - * - * Since: 2.32 - */ - - -/** - * g_dbus_connection_unexport_menu_model: - * @connection: a #GDBusConnection - * @export_id: the ID from g_dbus_connection_export_menu_model() - * - * Reverses the effect of a previous call to - * g_dbus_connection_export_menu_model(). - * - * It is an error to call this function with an ID that wasn't returned - * from g_dbus_connection_export_menu_model() or to call it with the - * same ID more than once. - * - * Since: 2.32 - */ - - -/** - * g_dbus_connection_unregister_object: - * @connection: a #GDBusConnection - * @registration_id: a registration id obtained from - * g_dbus_connection_register_object() - * - * Unregisters an object. - * - * Returns: %TRUE if the object was unregistered, %FALSE otherwise - * Since: 2.26 - */ - - -/** - * g_dbus_connection_unregister_subtree: - * @connection: a #GDBusConnection - * @registration_id: a subtree registration id obtained from - * g_dbus_connection_register_subtree() - * - * Unregisters a subtree. - * - * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise - * Since: 2.26 - */ - - -/** - * g_dbus_error_encode_gerror: - * @error: A #GError. - * - * Creates a D-Bus error name to use for @error. If @error matches - * a registered error (cf. g_dbus_error_register_error()), the corresponding - * D-Bus error name will be returned. - * - * Otherwise the a name of the form - * `org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE` - * will be used. This allows other GDBus applications to map the error - * on the wire back to a #GError using g_dbus_error_new_for_dbus_error(). - * - * This function is typically only used in object mappings to put a - * #GError on the wire. Regular applications should not use it. - * - * Returns: (transfer full) (not nullable): A D-Bus error name (never %NULL). - * Free with g_free(). - * Since: 2.26 - */ - - -/** - * g_dbus_error_get_remote_error: - * @error: a #GError - * - * Gets the D-Bus error name used for @error, if any. - * - * This function is guaranteed to return a D-Bus error name for all - * #GErrors returned from functions handling remote method calls - * (e.g. g_dbus_connection_call_finish()) unless - * g_dbus_error_strip_remote_error() has been used on @error. - * - * Returns: (nullable) (transfer full): an allocated string or %NULL if the - * D-Bus error name could not be found. Free with g_free(). - * Since: 2.26 - */ - - -/** - * g_dbus_error_is_remote_error: - * @error: A #GError. - * - * Checks if @error represents an error received via D-Bus from a remote peer. If so, - * use g_dbus_error_get_remote_error() to get the name of the error. - * - * Returns: %TRUE if @error represents an error from a remote peer, - * %FALSE otherwise. - * Since: 2.26 - */ - - -/** - * g_dbus_error_new_for_dbus_error: - * @dbus_error_name: D-Bus error name. - * @dbus_error_message: D-Bus error message. - * - * Creates a #GError based on the contents of @dbus_error_name and - * @dbus_error_message. - * - * Errors registered with g_dbus_error_register_error() will be looked - * up using @dbus_error_name and if a match is found, the error domain - * and code is used. Applications can use g_dbus_error_get_remote_error() - * to recover @dbus_error_name. - * - * If a match against a registered error is not found and the D-Bus - * error name is in a form as returned by g_dbus_error_encode_gerror() - * the error domain and code encoded in the name is used to - * create the #GError. Also, @dbus_error_name is added to the error message - * such that it can be recovered with g_dbus_error_get_remote_error(). - * - * Otherwise, a #GError with the error code %G_IO_ERROR_DBUS_ERROR - * in the #G_IO_ERROR error domain is returned. Also, @dbus_error_name is - * added to the error message such that it can be recovered with - * g_dbus_error_get_remote_error(). - * - * In all three cases, @dbus_error_name can always be recovered from the - * returned #GError using the g_dbus_error_get_remote_error() function - * (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error). - * - * This function is typically only used in object mappings to prepare - * #GError instances for applications. Regular applications should not use - * it. - * - * Returns: (transfer full): An allocated #GError. Free with g_error_free(). - * Since: 2.26 - */ - - -/** - * g_dbus_error_register_error: - * @error_domain: A #GQuark for an error domain. - * @error_code: An error code. - * @dbus_error_name: A D-Bus error name. - * - * Creates an association to map between @dbus_error_name and - * #GErrors specified by @error_domain and @error_code. - * - * This is typically done in the routine that returns the #GQuark for - * an error domain. - * - * Returns: %TRUE if the association was created, %FALSE if it already - * exists. - * Since: 2.26 - */ - - -/** - * g_dbus_error_register_error_domain: - * @error_domain_quark_name: The error domain name. - * @quark_volatile: A pointer where to store the #GQuark. - * @entries: (array length=num_entries): A pointer to @num_entries #GDBusErrorEntry struct items. - * @num_entries: Number of items to register. - * - * Helper function for associating a #GError error domain with D-Bus error names. - * - * While @quark_volatile has a `volatile` qualifier, this is a historical - * artifact and the argument passed to it should not be `volatile`. - * - * Since: 2.26 - */ - - -/** - * g_dbus_error_set_dbus_error: - * @error: A pointer to a #GError or %NULL. - * @dbus_error_name: D-Bus error name. - * @dbus_error_message: D-Bus error message. - * @format: (nullable): printf()-style format to prepend to @dbus_error_message or %NULL. - * @...: Arguments for @format. - * - * Does nothing if @error is %NULL. Otherwise sets *@error to - * a new #GError created with g_dbus_error_new_for_dbus_error() - * with @dbus_error_message prepend with @format (unless %NULL). - * - * Since: 2.26 - */ - - -/** - * g_dbus_error_set_dbus_error_valist: - * @error: A pointer to a #GError or %NULL. - * @dbus_error_name: D-Bus error name. - * @dbus_error_message: D-Bus error message. - * @format: (nullable): printf()-style format to prepend to @dbus_error_message or %NULL. - * @var_args: Arguments for @format. - * - * Like g_dbus_error_set_dbus_error() but intended for language bindings. - * - * Since: 2.26 - */ - - -/** - * g_dbus_error_strip_remote_error: - * @error: A #GError. - * - * Looks for extra information in the error message used to recover - * the D-Bus error name and strips it if found. If stripped, the - * message field in @error will correspond exactly to what was - * received on the wire. - * - * This is typically used when presenting errors to the end user. - * - * Returns: %TRUE if information was stripped, %FALSE otherwise. - * Since: 2.26 - */ - - -/** - * g_dbus_error_unregister_error: - * @error_domain: A #GQuark for an error domain. - * @error_code: An error code. - * @dbus_error_name: A D-Bus error name. - * - * Destroys an association previously set up with g_dbus_error_register_error(). - * - * Returns: %TRUE if the association was destroyed, %FALSE if it wasn't found. - * Since: 2.26 - */ - - -/** - * g_dbus_escape_object_path: - * @s: the string to escape - * - * This is a language binding friendly version of g_dbus_escape_object_path_bytestring(). - * - * Returns: an escaped version of @s. Free with g_free(). - * Since: 2.68 - */ - - -/** - * g_dbus_escape_object_path_bytestring: - * @bytes: (array zero-terminated=1) (element-type guint8): the string of bytes to escape - * - * Escapes @bytes for use in a D-Bus object path component. - * @bytes is an array of zero or more nonzero bytes in an - * unspecified encoding, followed by a single zero byte. - * - * The escaping method consists of replacing all non-alphanumeric - * characters (see g_ascii_isalnum()) with their hexadecimal value - * preceded by an underscore (`_`). For example: - * `foo.bar.baz` will become `foo_2ebar_2ebaz`. - * - * This method is appropriate to use when the input is nearly - * a valid object path component but is not when your input - * is far from being a valid object path component. - * Other escaping algorithms are also valid to use with - * D-Bus object paths. - * - * This can be reversed with g_dbus_unescape_object_path(). - * - * Returns: an escaped version of @bytes. Free with g_free(). - * Since: 2.68 - */ - - -/** - * g_dbus_generate_guid: - * - * Generate a D-Bus GUID that can be used with - * e.g. g_dbus_connection_new(). - * - * See the - * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#uuids) - * regarding what strings are valid D-Bus GUIDs. The specification refers to - * these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as - * ‘GUIDs’. The terms are interchangeable. - * - * Note that D-Bus GUIDs do not follow - * [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). - * - * Returns: A valid D-Bus GUID. Free with g_free(). - * Since: 2.26 - */ - - -/** - * g_dbus_gvalue_to_gvariant: - * @gvalue: A #GValue to convert to a #GVariant - * @type: A #GVariantType - * - * Converts a #GValue to a #GVariant of the type indicated by the @type - * parameter. - * - * The conversion is using the following rules: - * - * - #G_TYPE_STRING: 's', 'o', 'g' or 'ay' - * - #G_TYPE_STRV: 'as', 'ao' or 'aay' - * - #G_TYPE_BOOLEAN: 'b' - * - #G_TYPE_UCHAR: 'y' - * - #G_TYPE_INT: 'i', 'n' - * - #G_TYPE_UINT: 'u', 'q' - * - #G_TYPE_INT64 'x' - * - #G_TYPE_UINT64: 't' - * - #G_TYPE_DOUBLE: 'd' - * - #G_TYPE_VARIANT: Any #GVariantType - * - * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type - * is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType - * (including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not - * in the table above. - * - * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is - * %NULL, the empty #GVariant instance (never %NULL) for @type is - * returned (e.g. 0 for scalar types, the empty string for string types, - * '/' for object path types, the empty array for any array type and so on). - * - * See the g_dbus_gvariant_to_gvalue() function for how to convert a - * #GVariant to a #GValue. - * - * Returns: (transfer full): A #GVariant (never floating) of - * #GVariantType @type holding the data from @gvalue or an empty #GVariant - * in case of failure. Free with g_variant_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_gvariant_to_gvalue: - * @value: A #GVariant. - * @out_gvalue: (out): Return location pointing to a zero-filled (uninitialized) #GValue. - * - * Converts a #GVariant to a #GValue. If @value is floating, it is consumed. - * - * The rules specified in the g_dbus_gvalue_to_gvariant() function are - * used - this function is essentially its reverse form. So, a #GVariant - * containing any basic or string array type will be converted to a #GValue - * containing a basic value or string array. Any other #GVariant (handle, - * variant, tuple, dict entry) will be converted to a #GValue containing that - * #GVariant. - * - * The conversion never fails - a valid #GValue is always returned in - * @out_gvalue. - * - * Since: 2.30 - */ - - -/** - * g_dbus_interface_dup_object: (rename-to g_dbus_interface_get_object) - * @interface_: An exported D-Bus interface. - * - * Gets the #GDBusObject that @interface_ belongs to, if any. - * - * Returns: (nullable) (transfer full): A #GDBusObject or %NULL. The returned - * reference should be freed with g_object_unref(). - * Since: 2.32 - */ - - -/** - * g_dbus_interface_get_info: - * @interface_: An exported D-Bus interface. - * - * Gets D-Bus introspection information for the D-Bus interface - * implemented by @interface_. - * - * Returns: (transfer none): A #GDBusInterfaceInfo. Do not free. - * Since: 2.30 - */ - - -/** - * g_dbus_interface_get_object: (skip) - * @interface_: An exported D-Bus interface - * - * Gets the #GDBusObject that @interface_ belongs to, if any. - * - * It is not safe to use the returned object if @interface_ or - * the returned object is being used from other threads. See - * g_dbus_interface_dup_object() for a thread-safe alternative. - * - * Returns: (nullable) (transfer none): A #GDBusObject or %NULL. The returned - * reference belongs to @interface_ and should not be freed. - * Since: 2.30 - */ - - -/** - * g_dbus_interface_info_cache_build: - * @info: A #GDBusInterfaceInfo. - * - * Builds a lookup-cache to speed up - * g_dbus_interface_info_lookup_method(), - * g_dbus_interface_info_lookup_signal() and - * g_dbus_interface_info_lookup_property(). - * - * If this has already been called with @info, the existing cache is - * used and its use count is increased. - * - * Note that @info cannot be modified until - * g_dbus_interface_info_cache_release() is called. - * - * Since: 2.30 - */ - - -/** - * g_dbus_interface_info_cache_release: - * @info: A GDBusInterfaceInfo - * - * Decrements the usage count for the cache for @info built by - * g_dbus_interface_info_cache_build() (if any) and frees the - * resources used by the cache if the usage count drops to zero. - * - * Since: 2.30 - */ - - -/** - * g_dbus_interface_info_generate_xml: - * @info: A #GDBusNodeInfo - * @indent: Indentation level. - * @string_builder: A #GString to to append XML data to. - * - * Appends an XML representation of @info (and its children) to @string_builder. - * - * This function is typically used for generating introspection XML - * documents at run-time for handling the - * `org.freedesktop.DBus.Introspectable.Introspect` - * method. - * - * Since: 2.26 - */ - - -/** - * g_dbus_interface_info_lookup_method: - * @info: A #GDBusInterfaceInfo. - * @name: A D-Bus method name (typically in CamelCase) - * - * Looks up information about a method. - * - * 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: (nullable) (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. - * Since: 2.26 - */ - - -/** - * g_dbus_interface_info_lookup_property: - * @info: A #GDBusInterfaceInfo. - * @name: A D-Bus property name (typically in CamelCase). - * - * Looks up information about a property. - * - * 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: (nullable) (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. - * Since: 2.26 - */ - - -/** - * g_dbus_interface_info_lookup_signal: - * @info: A #GDBusInterfaceInfo. - * @name: A D-Bus signal name (typically in CamelCase) - * - * Looks up information about a signal. - * - * 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: (nullable) (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. - * Since: 2.26 - */ - - -/** - * g_dbus_interface_info_ref: - * @info: A #GDBusInterfaceInfo - * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. - * - * Returns: (not nullable): The same @info. - * Since: 2.26 - */ - - -/** - * g_dbus_interface_info_unref: - * @info: A #GDBusInterfaceInfo. - * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. - * - * Since: 2.26 - */ - - -/** - * g_dbus_interface_set_object: - * @interface_: An exported D-Bus interface. - * @object: (nullable): A #GDBusObject or %NULL. - * - * Sets the #GDBusObject for @interface_ to @object. - * - * Note that @interface_ will hold a weak reference to @object. - * - * Since: 2.30 - */ - - -/** - * g_dbus_interface_skeleton_export: - * @interface_: The D-Bus interface to export. - * @connection: A #GDBusConnection to export @interface_ on. - * @object_path: The path to export the interface at. - * @error: Return location for error or %NULL. - * - * Exports @interface_ at @object_path on @connection. - * - * This can be called multiple times to export the same @interface_ - * onto multiple connections however the @object_path provided must be - * the same for all connections. - * - * Use g_dbus_interface_skeleton_unexport() to unexport the object. - * - * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with - * @error set. - * Since: 2.30 - */ - - -/** - * g_dbus_interface_skeleton_flush: - * @interface_: A #GDBusInterfaceSkeleton. - * - * If @interface_ has outstanding changes, request for these changes to be - * emitted immediately. - * - * For example, an exported D-Bus interface may queue up property - * changes and emit the - * `org.freedesktop.DBus.Properties.PropertiesChanged` - * signal later (e.g. in an idle handler). This technique is useful - * for collapsing multiple property changes into one. - * - * Since: 2.30 - */ - - -/** - * g_dbus_interface_skeleton_get_connection: - * @interface_: A #GDBusInterfaceSkeleton. - * - * Gets the first connection that @interface_ is exported on, if any. - * - * Returns: (nullable) (transfer none): A #GDBusConnection or %NULL if @interface_ is - * not exported anywhere. Do not free, the object belongs to @interface_. - * Since: 2.30 - */ - - -/** - * g_dbus_interface_skeleton_get_connections: - * @interface_: A #GDBusInterfaceSkeleton. - * - * Gets a list of the connections that @interface_ is exported on. - * - * Returns: (element-type GDBusConnection) (transfer full): A list of - * all the connections that @interface_ is exported on. The returned - * list should be freed with g_list_free() after each element has - * been freed with g_object_unref(). - * Since: 2.32 - */ - - -/** - * g_dbus_interface_skeleton_get_flags: - * @interface_: A #GDBusInterfaceSkeleton. - * - * Gets the #GDBusInterfaceSkeletonFlags that describes what the behavior - * of @interface_ - * - * Returns: One or more flags from the #GDBusInterfaceSkeletonFlags enumeration. - * Since: 2.30 - */ - - -/** - * g_dbus_interface_skeleton_get_info: - * @interface_: A #GDBusInterfaceSkeleton. - * - * Gets D-Bus introspection information for the D-Bus interface - * implemented by @interface_. - * - * Returns: (transfer none): A #GDBusInterfaceInfo (never %NULL). Do not free. - * Since: 2.30 - */ - - -/** - * g_dbus_interface_skeleton_get_object_path: - * @interface_: A #GDBusInterfaceSkeleton. - * - * Gets the object path that @interface_ is exported on, if any. - * - * Returns: (nullable): A string owned by @interface_ or %NULL if @interface_ is not exported - * anywhere. Do not free, the string belongs to @interface_. - * Since: 2.30 - */ - - -/** - * g_dbus_interface_skeleton_get_properties: - * @interface_: A #GDBusInterfaceSkeleton. - * - * Gets all D-Bus properties for @interface_. - * - * Returns: (transfer full): A #GVariant of type - * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. - * Free with g_variant_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_interface_skeleton_get_vtable: (skip) - * @interface_: A #GDBusInterfaceSkeleton. - * - * Gets the interface vtable for the D-Bus interface implemented by - * @interface_. The returned function pointers should expect @interface_ - * itself to be passed as @user_data. - * - * Returns: A #GDBusInterfaceVTable (never %NULL). - * Since: 2.30 - */ - - -/** - * g_dbus_interface_skeleton_has_connection: - * @interface_: A #GDBusInterfaceSkeleton. - * @connection: A #GDBusConnection. - * - * Checks if @interface_ is exported on @connection. - * - * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise. - * Since: 2.32 - */ - - -/** - * g_dbus_interface_skeleton_set_flags: - * @interface_: A #GDBusInterfaceSkeleton. - * @flags: Flags from the #GDBusInterfaceSkeletonFlags enumeration. - * - * Sets flags describing what the behavior of @skeleton should be. - * - * Since: 2.30 - */ - - -/** - * g_dbus_interface_skeleton_unexport: - * @interface_: A #GDBusInterfaceSkeleton. - * - * Stops exporting @interface_ on all connections it is exported on. - * - * To unexport @interface_ from only a single connection, use - * g_dbus_interface_skeleton_unexport_from_connection() - * - * Since: 2.30 - */ - - -/** - * g_dbus_interface_skeleton_unexport_from_connection: - * @interface_: A #GDBusInterfaceSkeleton. - * @connection: A #GDBusConnection. - * - * Stops exporting @interface_ on @connection. - * - * To stop exporting on all connections the interface is exported on, - * use g_dbus_interface_skeleton_unexport(). - * - * Since: 2.32 - */ - - -/** - * g_dbus_is_address: - * @string: A string. - * - * Checks if @string is a - * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - * - * This doesn't check if @string is actually supported by #GDBusServer - * or #GDBusConnection - use g_dbus_is_supported_address() to do more - * checks. - * - * Returns: %TRUE if @string is a valid D-Bus address, %FALSE otherwise. - * Since: 2.26 - */ - - -/** - * g_dbus_is_error_name: - * @string: The string to check. - * - * Check whether @string is a valid D-Bus error name. - * - * This function returns the same result as g_dbus_is_interface_name(), - * because D-Bus error names are defined to have exactly the - * same syntax as interface names. - * - * Returns: %TRUE if valid, %FALSE otherwise. - * Since: 2.70 - */ - - -/** - * g_dbus_is_guid: - * @string: The string to check. - * - * Checks if @string is a D-Bus GUID. - * - * See the documentation for g_dbus_generate_guid() for more information about - * the format of a GUID. - * - * Returns: %TRUE if @string is a GUID, %FALSE otherwise. - * Since: 2.26 - */ - - -/** - * g_dbus_is_interface_name: - * @string: The string to check. - * - * Checks if @string is a valid D-Bus interface name. - * - * Returns: %TRUE if valid, %FALSE otherwise. - * Since: 2.26 - */ - - -/** - * g_dbus_is_member_name: - * @string: The string to check. - * - * Checks if @string is a valid D-Bus member (e.g. signal or method) name. - * - * Returns: %TRUE if valid, %FALSE otherwise. - * Since: 2.26 - */ - - -/** - * g_dbus_is_name: - * @string: The string to check. - * - * Checks if @string is a valid D-Bus bus name (either unique or well-known). - * - * Returns: %TRUE if valid, %FALSE otherwise. - * Since: 2.26 - */ - - -/** - * g_dbus_is_supported_address: - * @string: A string. - * @error: Return location for error or %NULL. - * - * Like g_dbus_is_address() but also checks if the library supports the - * transports in @string and that key/value pairs for each transport - * are valid. See the specification of the - * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). - * - * Returns: %TRUE if @string is a valid D-Bus address that is - * supported by this library, %FALSE if @error is set. - * Since: 2.26 - */ - - -/** - * g_dbus_is_unique_name: - * @string: The string to check. - * - * Checks if @string is a valid D-Bus unique bus name. - * - * Returns: %TRUE if valid, %FALSE otherwise. - * Since: 2.26 - */ - - -/** - * g_dbus_menu_model_get: - * @connection: a #GDBusConnection - * @bus_name: (nullable): the bus name which exports the menu model - * or %NULL if @connection is not a message bus connection - * @object_path: the object path at which the menu model is exported - * - * Obtains a #GDBusMenuModel for the menu model which is exported - * at the given @bus_name and @object_path. - * - * The thread default main context is taken at the time of this call. - * All signals on the menu model (and any linked models) are reported - * with respect to this context. All calls on the returned menu model - * (and linked models) must also originate from this same context, with - * the thread default main context unchanged. - * - * Returns: (transfer full): a #GDBusMenuModel object. Free with - * g_object_unref(). - * Since: 2.32 - */ - - -/** - * g_dbus_message_bytes_needed: - * @blob: (array length=blob_len) (element-type guint8): A blob representing a binary D-Bus message. - * @blob_len: The length of @blob (must be at least 16). - * @error: Return location for error or %NULL. - * - * Utility function to calculate how many bytes are needed to - * completely deserialize the D-Bus message stored at @blob. - * - * Returns: Number of bytes needed or -1 if @error is set (e.g. if - * @blob contains invalid data or not enough data is available to - * determine the size). - * Since: 2.26 - */ - - -/** - * g_dbus_message_copy: - * @message: A #GDBusMessage. - * @error: Return location for error or %NULL. - * - * Copies @message. The copy is a deep copy and the returned - * #GDBusMessage is completely identical except that it is guaranteed - * to not be locked. - * - * This operation can fail if e.g. @message contains file descriptors - * and the per-process or system-wide open files limit is reached. - * - * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. - * Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_arg0: - * @message: A #GDBusMessage. - * - * Convenience to get the first item in the body of @message. - * - * Returns: (nullable): The string item or %NULL if the first item in the body of - * @message is not a string. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_body: - * @message: A #GDBusMessage. - * - * Gets the body of a message. - * - * Returns: (nullable) (transfer none): A #GVariant or %NULL if the body is - * empty. Do not free, it is owned by @message. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_byte_order: - * @message: A #GDBusMessage. - * - * Gets the byte order of @message. - * - * Returns: The byte order. - */ - - -/** - * g_dbus_message_get_destination: - * @message: A #GDBusMessage. - * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. - * - * Returns: (nullable): The value. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_error_name: - * @message: A #GDBusMessage. - * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. - * - * Returns: (nullable): The value. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_flags: - * @message: A #GDBusMessage. - * - * Gets the flags for @message. - * - * Returns: Flags that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_header: - * @message: A #GDBusMessage. - * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) - * - * Gets a header field on @message. - * - * The caller is responsible for checking the type of the returned #GVariant - * matches what is expected. - * - * Returns: (transfer none) (nullable): A #GVariant with the value if the header was found, %NULL - * otherwise. Do not free, it is owned by @message. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_header_fields: - * @message: A #GDBusMessage. - * - * Gets an array of all header fields on @message that are set. - * - * Returns: (array zero-terminated=1): An array of header fields - * terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element - * is a #guchar. Free with g_free(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_interface: - * @message: A #GDBusMessage. - * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. - * - * Returns: (nullable): The value. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_locked: - * @message: A #GDBusMessage. - * - * Checks whether @message is locked. To monitor changes to this - * value, conncet to the #GObject::notify signal to listen for changes - * on the #GDBusMessage:locked property. - * - * Returns: %TRUE if @message is locked, %FALSE otherwise. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_member: - * @message: A #GDBusMessage. - * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. - * - * Returns: (nullable): The value. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_message_type: - * @message: A #GDBusMessage. - * - * Gets the type of @message. - * - * Returns: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_num_unix_fds: - * @message: A #GDBusMessage. - * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. - * - * Returns: The value. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_path: - * @message: A #GDBusMessage. - * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. - * - * Returns: (nullable): The value. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_reply_serial: - * @message: A #GDBusMessage. - * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. - * - * Returns: The value. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_sender: - * @message: A #GDBusMessage. - * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. - * - * Returns: (nullable): The value. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_serial: - * @message: A #GDBusMessage. - * - * Gets the serial for @message. - * - * Returns: A #guint32. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_signature: - * @message: A #GDBusMessage. - * - * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. - * - * This will always be non-%NULL, but may be an empty string. - * - * Returns: (not nullable): The value. - * Since: 2.26 - */ - - -/** - * g_dbus_message_get_unix_fd_list: - * @message: A #GDBusMessage. - * - * Gets the UNIX file descriptors associated with @message, if any. - * - * This method is only available on UNIX. - * - * The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE - * values in the body of the message. For example, - * if g_variant_get_handle() returns 5, that is intended to be a reference - * to the file descriptor that can be accessed by - * `g_unix_fd_list_get (list, 5, ...)`. - * - * Returns: (nullable) (transfer none): A #GUnixFDList or %NULL if no file descriptors are - * associated. Do not free, this object is owned by @message. - * Since: 2.26 - */ - - -/** - * g_dbus_message_lock: - * @message: A #GDBusMessage. - * - * If @message is locked, does nothing. Otherwise locks the message. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_new: - * - * Creates a new empty #GDBusMessage. - * - * Returns: A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_new_from_blob: - * @blob: (array length=blob_len) (element-type guint8): A blob representing a binary D-Bus message. - * @blob_len: The length of @blob. - * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported. - * @error: Return location for error or %NULL. - * - * Creates a new #GDBusMessage from the data stored at @blob. The byte - * order that the message was in can be retrieved using - * g_dbus_message_get_byte_order(). - * - * If the @blob cannot be parsed, contains invalid fields, or contains invalid - * headers, %G_IO_ERROR_INVALID_ARGUMENT will be returned. - * - * Returns: A new #GDBusMessage or %NULL if @error is set. Free with - * g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_new_method_call: - * @name: (nullable): A valid D-Bus name or %NULL. - * @path: A valid object path. - * @interface_: (nullable): A valid D-Bus interface name or %NULL. - * @method: A valid method name. - * - * Creates a new #GDBusMessage for a method call. - * - * Returns: A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_new_method_error: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to - * create a reply message to. - * @error_name: A valid D-Bus error name. - * @error_message_format: The D-Bus error message in a printf() format. - * @...: Arguments for @error_message_format. - * - * Creates a new #GDBusMessage that is an error reply to @method_call_message. - * - * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_new_method_error_literal: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to - * create a reply message to. - * @error_name: A valid D-Bus error name. - * @error_message: The D-Bus error message. - * - * Creates a new #GDBusMessage that is an error reply to @method_call_message. - * - * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_new_method_error_valist: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to - * create a reply message to. - * @error_name: A valid D-Bus error name. - * @error_message_format: The D-Bus error message in a printf() format. - * @var_args: Arguments for @error_message_format. - * - * Like g_dbus_message_new_method_error() but intended for language bindings. - * - * Returns: (transfer full): A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_new_method_reply: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to - * create a reply message to. - * - * Creates a new #GDBusMessage that is a reply to @method_call_message. - * - * Returns: (transfer full): #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_new_signal: - * @path: A valid object path. - * @interface_: A valid D-Bus interface name. - * @signal: A valid signal name. - * - * Creates a new #GDBusMessage for a signal emission. - * - * Returns: A #GDBusMessage. Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_print: (type method-return) - * @message: A #GDBusMessage. - * @indent: Indentation level. - * - * Produces a human-readable multi-line description of @message. - * - * The contents of the description has no ABI guarantees, the contents - * and formatting is subject to change at any time. Typical output - * looks something like this: - * |[ - * Flags: none - * Version: 0 - * Serial: 4 - * Headers: - * path -> objectpath '/org/gtk/GDBus/TestObject' - * interface -> 'org.gtk.GDBus.TestInterface' - * member -> 'GimmeStdout' - * destination -> ':1.146' - * Body: () - * UNIX File Descriptors: - * (none) - * ]| - * or - * |[ - * Flags: no-reply-expected - * Version: 0 - * Serial: 477 - * Headers: - * reply-serial -> uint32 4 - * destination -> ':1.159' - * sender -> ':1.146' - * num-unix-fds -> uint32 1 - * Body: () - * UNIX File Descriptors: - * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635 - * ]| - * - * Returns: (not nullable): A string that should be freed with g_free(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_body: - * @message: A #GDBusMessage. - * @body: Either %NULL or a #GVariant that is a tuple. - * - * Sets the body @message. As a side-effect the - * %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the - * type string of @body (or cleared if @body is %NULL). - * - * If @body is floating, @message assumes ownership of @body. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_byte_order: - * @message: A #GDBusMessage. - * @byte_order: The byte order. - * - * Sets the byte order of @message. - */ - - -/** - * g_dbus_message_set_destination: - * @message: A #GDBusMessage. - * @value: (nullable): The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_error_name: - * @message: (nullable): A #GDBusMessage. - * @value: The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_flags: - * @message: A #GDBusMessage. - * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags - * enumeration bitwise ORed together). - * - * Sets the flags to set on @message. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_header: - * @message: A #GDBusMessage. - * @header_field: A 8-bit unsigned integer (typically a value from the #GDBusMessageHeaderField enumeration) - * @value: (nullable): A #GVariant to set the header field or %NULL to clear the header field. - * - * Sets a header field on @message. - * - * If @value is floating, @message assumes ownership of @value. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_interface: - * @message: A #GDBusMessage. - * @value: (nullable): The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_member: - * @message: A #GDBusMessage. - * @value: (nullable): The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_message_type: - * @message: A #GDBusMessage. - * @type: A 8-bit unsigned integer (typically a value from the #GDBusMessageType enumeration). - * - * Sets @message to be of @type. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_num_unix_fds: - * @message: A #GDBusMessage. - * @value: The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_path: - * @message: A #GDBusMessage. - * @value: (nullable): The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_reply_serial: - * @message: A #GDBusMessage. - * @value: The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_sender: - * @message: A #GDBusMessage. - * @value: (nullable): The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_serial: - * @message: A #GDBusMessage. - * @serial: A #guint32. - * - * Sets the serial for @message. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_signature: - * @message: A #GDBusMessage. - * @value: (nullable): The value to set. - * - * Convenience setter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_set_unix_fd_list: - * @message: A #GDBusMessage. - * @fd_list: (nullable): A #GUnixFDList or %NULL. - * - * Sets the UNIX file descriptors associated with @message. As a - * side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header - * field is set to the number of fds in @fd_list (or cleared if - * @fd_list is %NULL). - * - * This method is only available on UNIX. - * - * When designing D-Bus APIs that are intended to be interoperable, - * please note that non-GDBus implementations of D-Bus can usually only - * access file descriptors if they are referenced by a value of type - * %G_VARIANT_TYPE_HANDLE in the body of the message. - * - * Since: 2.26 - */ - - -/** - * g_dbus_message_to_blob: - * @message: A #GDBusMessage. - * @out_size: Return location for size of generated blob. - * @capabilities: A #GDBusCapabilityFlags describing what protocol features are supported. - * @error: Return location for error. - * - * Serializes @message to a blob. The byte order returned by - * g_dbus_message_get_byte_order() will be used. - * - * Returns: (array length=out_size) (transfer full): A pointer to a - * valid binary D-Bus message of @out_size bytes generated by @message - * or %NULL if @error is set. Free with g_free(). - * Since: 2.26 - */ - - -/** - * g_dbus_message_to_gerror: - * @message: A #GDBusMessage. - * @error: The #GError to set. - * - * If @message is not of type %G_DBUS_MESSAGE_TYPE_ERROR does - * nothing and returns %FALSE. - * - * Otherwise this method encodes the error in @message as a #GError - * using g_dbus_error_set_dbus_error() using the information in the - * %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of @message as - * well as the first string item in @message's body. - * - * Returns: %TRUE if @error was set, %FALSE otherwise. - * Since: 2.26 - */ - - -/** - * g_dbus_method_info_ref: - * @info: A #GDBusMethodInfo - * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. - * - * Returns: (not nullable): The same @info. - * Since: 2.26 - */ - - -/** - * g_dbus_method_info_unref: - * @info: A #GDBusMethodInfo. - * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. - * - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_get_connection: - * @invocation: A #GDBusMethodInvocation. - * - * Gets the #GDBusConnection the method was invoked on. - * - * Returns: (transfer none): A #GDBusConnection. Do not free, it is owned by @invocation. - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_get_interface_name: - * @invocation: A #GDBusMethodInvocation. - * - * 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 - */ - - -/** - * g_dbus_method_invocation_get_message: - * @invocation: A #GDBusMethodInvocation. - * - * Gets the #GDBusMessage for the method invocation. This is useful if - * you need to use low-level protocol features, such as UNIX file - * descriptor passing, that cannot be properly expressed in the - * #GVariant API. - * - * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] - * for an example of how to use this low-level API to send and receive - * UNIX file descriptors. - * - * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation. - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_get_method_info: - * @invocation: A #GDBusMethodInvocation. - * - * 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: (nullable): A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_get_method_name: - * @invocation: A #GDBusMethodInvocation. - * - * Gets the name of the method that was invoked. - * - * Returns: A string. Do not free, it is owned by @invocation. - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_get_object_path: - * @invocation: A #GDBusMethodInvocation. - * - * Gets the object path the method was invoked on. - * - * Returns: A string. Do not free, it is owned by @invocation. - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_get_parameters: - * @invocation: A #GDBusMethodInvocation. - * - * Gets the parameters of the method invocation. If there are no input - * parameters then this will return a GVariant with 0 children rather than NULL. - * - * Returns: (transfer none): A #GVariant tuple. Do not unref this because it is owned by @invocation. - * Since: 2.26 - */ - - -/** - * 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: (nullable) (transfer none): a #GDBusPropertyInfo or %NULL - * Since: 2.38 - */ - - -/** - * g_dbus_method_invocation_get_sender: - * @invocation: A #GDBusMethodInvocation. - * - * Gets the bus name that invoked the method. - * - * Returns: A string. Do not free, it is owned by @invocation. - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_get_user_data: (skip) - * @invocation: A #GDBusMethodInvocation. - * - * Gets the @user_data #gpointer passed to g_dbus_connection_register_object(). - * - * Returns: A #gpointer. - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_return_dbus_error: - * @invocation: (transfer full): A #GDBusMethodInvocation. - * @error_name: A valid D-Bus error name. - * @error_message: A valid D-Bus error message. - * - * Finishes handling a D-Bus method call by returning an error. - * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. - * - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_return_error: - * @invocation: (transfer full): A #GDBusMethodInvocation. - * @domain: A #GQuark for the #GError error domain. - * @code: The error code. - * @format: printf()-style format. - * @...: Parameters for @format. - * - * Finishes handling a D-Bus method call by returning an error. - * - * See g_dbus_error_encode_gerror() for details about what error name - * will be returned on the wire. In a nutshell, if the given error is - * registered using g_dbus_error_register_error() the name given - * during registration is used. Otherwise, a name of the form - * `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides - * transparent mapping of #GError between applications using GDBus. - * - * If you are writing an application intended to be portable, - * always register errors with g_dbus_error_register_error() - * or use g_dbus_method_invocation_return_dbus_error(). - * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. - * - * Since 2.48, if the method call requested for a reply not to be sent - * then this call will free @invocation but otherwise do nothing (as per - * the recommendations of the D-Bus specification). - * - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_return_error_literal: - * @invocation: (transfer full): A #GDBusMethodInvocation. - * @domain: A #GQuark for the #GError error domain. - * @code: The error code. - * @message: The error message. - * - * Like g_dbus_method_invocation_return_error() but without printf()-style formatting. - * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. - * - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_return_error_valist: - * @invocation: (transfer full): A #GDBusMethodInvocation. - * @domain: A #GQuark for the #GError error domain. - * @code: The error code. - * @format: printf()-style format. - * @var_args: #va_list of parameters for @format. - * - * Like g_dbus_method_invocation_return_error() but intended for - * language bindings. - * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. - * - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_return_gerror: - * @invocation: (transfer full): A #GDBusMethodInvocation. - * @error: A #GError. - * - * Like g_dbus_method_invocation_return_error() but takes a #GError - * instead of the error domain, error code and message. - * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. - * - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_return_value: - * @invocation: (transfer full): A #GDBusMethodInvocation. - * @parameters: (nullable): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. - * - * Finishes handling a D-Bus method call by returning @parameters. - * If the @parameters GVariant is floating, it is consumed. - * - * It is an error if @parameters is not of the right format: it must be a tuple - * containing the out-parameters of the D-Bus method. Even if the method has a - * single out-parameter, it must be contained in a tuple. If the method has no - * out-parameters, @parameters may be %NULL or an empty tuple. - * - * |[ - * GDBusMethodInvocation *invocation = some_invocation; - * g_autofree gchar *result_string = NULL; - * g_autoptr (GError) error = NULL; - * - * result_string = calculate_result (&error); - * - * if (error != NULL) - * g_dbus_method_invocation_return_gerror (invocation, error); - * else - * g_dbus_method_invocation_return_value (invocation, - * g_variant_new ("(s)", result_string)); - * - * // Do not free @invocation here; returning a value does that - * ]| - * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. - * - * Since 2.48, if the method call requested for a reply not to be sent - * then this call will sink @parameters and free @invocation, but - * otherwise do nothing (as per the recommendations of the D-Bus - * specification). - * - * Since: 2.26 - */ - - -/** - * g_dbus_method_invocation_return_value_with_unix_fd_list: - * @invocation: (transfer full): A #GDBusMethodInvocation. - * @parameters: (nullable): A #GVariant tuple with out parameters for the method or %NULL if not passing any parameters. - * @fd_list: (nullable): A #GUnixFDList or %NULL. - * - * Like g_dbus_method_invocation_return_value() but also takes a #GUnixFDList. - * - * This method is only available on UNIX. - * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. - * - * Since: 2.30 - */ - - -/** - * g_dbus_method_invocation_take_error: (skip) - * @invocation: (transfer full): A #GDBusMethodInvocation. - * @error: (transfer full): A #GError. - * - * Like g_dbus_method_invocation_return_gerror() but takes ownership - * of @error so the caller does not need to free it. - * - * This method will take ownership of @invocation. See - * #GDBusInterfaceVTable for more information about the ownership of - * @invocation. - * - * Since: 2.30 - */ - - -/** - * g_dbus_node_info_generate_xml: - * @info: A #GDBusNodeInfo. - * @indent: Indentation level. - * @string_builder: A #GString to to append XML data to. - * - * Appends an XML representation of @info (and its children) to @string_builder. - * - * This function is typically used for generating introspection XML documents at run-time for - * handling the `org.freedesktop.DBus.Introspectable.Introspect` method. - * - * Since: 2.26 - */ - - -/** - * g_dbus_node_info_lookup_interface: - * @info: A #GDBusNodeInfo. - * @name: A D-Bus interface name. - * - * Looks up information about an interface. - * - * The cost of this function is O(n) in number of interfaces. - * - * Returns: (nullable) (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. - * Since: 2.26 - */ - - -/** - * g_dbus_node_info_new_for_xml: - * @xml_data: Valid D-Bus introspection XML. - * @error: Return location for error. - * - * Parses @xml_data and returns a #GDBusNodeInfo representing the data. - * - * The introspection XML must contain exactly one top-level - * element. - * - * Note that this routine is using a - * [GMarkup][glib-Simple-XML-Subset-Parser.description]-based - * parser that only accepts a subset of valid XML documents. - * - * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free - * with g_dbus_node_info_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_node_info_ref: - * @info: A #GDBusNodeInfo - * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. - * - * Returns: (not nullable): The same @info. - * Since: 2.26 - */ - - -/** - * g_dbus_node_info_unref: - * @info: A #GDBusNodeInfo. - * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. - * - * Since: 2.26 - */ - - -/** - * g_dbus_object_get_interface: - * @object: A #GDBusObject. - * @interface_name: A D-Bus interface name. - * - * Gets the D-Bus interface with name @interface_name associated with - * @object, if any. - * - * Returns: (nullable) (transfer full): %NULL if not found, otherwise a - * #GDBusInterface that must be freed with g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_get_interfaces: - * @object: A #GDBusObject. - * - * Gets the D-Bus interfaces associated with @object. - * - * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances. - * The returned list must be freed by g_list_free() after each element has been freed - * with g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_get_object_path: - * @object: A #GDBusObject. - * - * Gets the object path for @object. - * - * Returns: A string owned by @object. Do not free. - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_client_get_connection: - * @manager: A #GDBusObjectManagerClient - * - * Gets the #GDBusConnection used by @manager. - * - * Returns: (transfer none): A #GDBusConnection object. Do not free, - * the object belongs to @manager. - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_client_get_flags: - * @manager: A #GDBusObjectManagerClient - * - * Gets the flags that @manager was constructed with. - * - * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags - * enumeration. - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_client_get_name: - * @manager: A #GDBusObjectManagerClient - * - * 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 - */ - - -/** - * g_dbus_object_manager_client_get_name_owner: - * @manager: A #GDBusObjectManagerClient. - * - * The unique name that owns the name that @manager is for or %NULL if - * no-one currently owns that name. You can connect to the - * #GObject::notify signal to track changes to the - * #GDBusObjectManagerClient:name-owner property. - * - * Returns: (nullable): The name owner or %NULL if no name owner - * exists. Free with g_free(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_client_new: - * @connection: A #GDBusConnection. - * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - * @name: The owner of the control object (unique or well-known name). - * @object_path: The object path of the control object. - * @get_proxy_type_func: (nullable): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. - * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func. - * @get_proxy_type_destroy_notify: (nullable): Free function for @get_proxy_type_user_data or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. - * - * Asynchronously creates a new #GDBusObjectManagerClient object. - * - * This is an asynchronous failable constructor. When the result is - * ready, @callback will be invoked in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this method from. You can - * then call g_dbus_object_manager_client_new_finish() to get the result. See - * g_dbus_object_manager_client_new_sync() for the synchronous version. - * - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_client_new_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new(). - * @error: Return location for error or %NULL. - * - * Finishes an operation started with g_dbus_object_manager_client_new(). - * - * Returns: (transfer full) (type GDBusObjectManagerClient): A - * #GDBusObjectManagerClient object or %NULL if @error is set. Free - * with g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_client_new_for_bus: - * @bus_type: A #GBusType. - * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - * @name: The owner of the control object (unique or well-known name). - * @object_path: The object path of the control object. - * @get_proxy_type_func: (nullable): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. - * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func. - * @get_proxy_type_destroy_notify: (nullable): Free function for @get_proxy_type_user_data or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. - * - * Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a - * #GDBusConnection. - * - * This is an asynchronous failable constructor. When the result is - * ready, @callback will be invoked in the - * [thread-default main loop][g-main-context-push-thread-default] - * of the thread you are calling this method from. You can - * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See - * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. - * - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_client_new_for_bus_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_object_manager_client_new_for_bus(). - * @error: Return location for error or %NULL. - * - * Finishes an operation started with g_dbus_object_manager_client_new_for_bus(). - * - * Returns: (transfer full) (type GDBusObjectManagerClient): A - * #GDBusObjectManagerClient object or %NULL if @error is set. Free - * with g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_client_new_for_bus_sync: - * @bus_type: A #GBusType. - * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - * @name: The owner of the control object (unique or well-known name). - * @object_path: The object path of the control object. - * @get_proxy_type_func: (nullable): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. - * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func. - * @get_proxy_type_destroy_notify: (nullable): Free function for @get_proxy_type_user_data or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL - * @error: Return location for error or %NULL. - * - * Like g_dbus_object_manager_client_new_sync() but takes a #GBusType instead - * of a #GDBusConnection. - * - * This is a synchronous failable constructor - the calling thread is - * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus() - * for the asynchronous version. - * - * Returns: (transfer full) (type GDBusObjectManagerClient): A - * #GDBusObjectManagerClient object or %NULL if @error is set. Free - * with g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_client_new_sync: - * @connection: A #GDBusConnection. - * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - * @name: (nullable): 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: (nullable): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. - * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func. - * @get_proxy_type_destroy_notify: (nullable): Free function for @get_proxy_type_user_data or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL - * @error: Return location for error or %NULL. - * - * Creates a new #GDBusObjectManagerClient object. - * - * This is a synchronous failable constructor - the calling thread is - * blocked until a reply is received. See g_dbus_object_manager_client_new() - * for the asynchronous version. - * - * Returns: (transfer full) (type GDBusObjectManagerClient): A - * #GDBusObjectManagerClient object or %NULL if @error is set. Free - * with g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_get_interface: - * @manager: A #GDBusObjectManager. - * @object_path: Object path to look up. - * @interface_name: D-Bus interface name to look up. - * - * Gets the interface proxy for @interface_name at @object_path, if - * any. - * - * Returns: (transfer full) (nullable): A #GDBusInterface instance or %NULL. Free - * with g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_get_object: - * @manager: A #GDBusObjectManager. - * @object_path: Object path to look up. - * - * Gets the #GDBusObjectProxy at @object_path, if any. - * - * Returns: (transfer full) (nullable): A #GDBusObject or %NULL. Free with - * g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_get_object_path: - * @manager: A #GDBusObjectManager. - * - * Gets the object path that @manager is for. - * - * Returns: A string owned by @manager. Do not free. - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_get_objects: - * @manager: A #GDBusObjectManager. - * - * Gets all #GDBusObject objects known to @manager. - * - * Returns: (transfer full) (element-type GDBusObject): A list of - * #GDBusObject objects. The returned list should be freed with - * g_list_free() after each element has been freed with - * g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_server_export: - * @manager: A #GDBusObjectManagerServer. - * @object: A #GDBusObjectSkeleton. - * - * Exports @object on @manager. - * - * If there is already a #GDBusObject exported at the object path, - * then the old object is removed. - * - * The object path for @object must be in the hierarchy rooted by the - * object path for @manager. - * - * Note that @manager will take a reference on @object for as long as - * it is exported. - * - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_server_export_uniquely: - * @manager: A #GDBusObjectManagerServer. - * @object: An object. - * - * Like g_dbus_object_manager_server_export() but appends a string of - * the form _N (with N being a natural number) to @object's object path - * if an object with the given path already exists. As such, the - * #GDBusObjectProxy:g-object-path property of @object may be modified. - * - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_server_get_connection: - * @manager: A #GDBusObjectManagerServer - * - * Gets the #GDBusConnection used by @manager. - * - * Returns: (transfer full) (nullable): A #GDBusConnection object or %NULL if - * @manager isn't exported on a connection. The returned object should - * be freed with g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_server_is_exported: - * @manager: A #GDBusObjectManagerServer. - * @object: An object. - * - * Returns whether @object is currently exported on @manager. - * - * Returns: %TRUE if @object is exported - * Since: 2.34 - */ - - -/** - * g_dbus_object_manager_server_new: - * @object_path: The object path to export the manager object at. - * - * Creates a new #GDBusObjectManagerServer object. - * - * The returned server isn't yet exported on any connection. To do so, - * use g_dbus_object_manager_server_set_connection(). Normally you - * want to export all of your objects before doing so to avoid - * [InterfacesAdded](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) - * signals being emitted. - * - * Returns: A #GDBusObjectManagerServer object. Free with g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_manager_server_set_connection: - * @manager: A #GDBusObjectManagerServer. - * @connection: (nullable): A #GDBusConnection or %NULL. - * - * Exports all objects managed by @manager on @connection. If - * @connection is %NULL, stops exporting objects. - */ - - -/** - * g_dbus_object_manager_server_unexport: - * @manager: A #GDBusObjectManagerServer. - * @object_path: An object path. - * - * If @manager has an object at @path, removes the object. Otherwise - * does nothing. - * - * Note that @object_path must be in the hierarchy rooted by the - * object path for @manager. - * - * Returns: %TRUE if object at @object_path was removed, %FALSE otherwise. - * Since: 2.30 - */ - - -/** - * g_dbus_object_proxy_get_connection: - * @proxy: a #GDBusObjectProxy - * - * Gets the connection that @proxy is for. - * - * Returns: (transfer none): A #GDBusConnection. Do not free, the - * object is owned by @proxy. - * Since: 2.30 - */ - - -/** - * g_dbus_object_proxy_new: - * @connection: a #GDBusConnection - * @object_path: the object path - * - * Creates a new #GDBusObjectProxy for the given connection and - * object path. - * - * Returns: a new #GDBusObjectProxy - * Since: 2.30 - */ - - -/** - * g_dbus_object_skeleton_add_interface: - * @object: A #GDBusObjectSkeleton. - * @interface_: A #GDBusInterfaceSkeleton. - * - * Adds @interface_ to @object. - * - * If @object already contains a #GDBusInterfaceSkeleton with the same - * interface name, it is removed before @interface_ is added. - * - * Note that @object takes its own reference on @interface_ and holds - * it until removed. - * - * Since: 2.30 - */ - - -/** - * g_dbus_object_skeleton_flush: - * @object: A #GDBusObjectSkeleton. - * - * This method simply calls g_dbus_interface_skeleton_flush() on all - * interfaces belonging to @object. See that method for when flushing - * is useful. - * - * Since: 2.30 - */ - - -/** - * g_dbus_object_skeleton_new: - * @object_path: An object path. - * - * Creates a new #GDBusObjectSkeleton. - * - * Returns: A #GDBusObjectSkeleton. Free with g_object_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_object_skeleton_remove_interface: - * @object: A #GDBusObjectSkeleton. - * @interface_: A #GDBusInterfaceSkeleton. - * - * Removes @interface_ from @object. - * - * Since: 2.30 - */ - - -/** - * g_dbus_object_skeleton_remove_interface_by_name: - * @object: A #GDBusObjectSkeleton. - * @interface_name: A D-Bus interface name. - * - * Removes the #GDBusInterface with @interface_name from @object. - * - * If no D-Bus interface of the given interface exists, this function - * does nothing. - * - * Since: 2.30 - */ - - -/** - * g_dbus_object_skeleton_set_object_path: - * @object: A #GDBusObjectSkeleton. - * @object_path: A valid D-Bus object path. - * - * Sets the object path for @object. - * - * Since: 2.30 - */ - - -/** - * g_dbus_property_info_ref: - * @info: A #GDBusPropertyInfo - * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. - * - * Returns: (not nullable): The same @info. - * Since: 2.26 - */ - - -/** - * g_dbus_property_info_unref: - * @info: A #GDBusPropertyInfo. - * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. - * - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_call: - * @proxy: A #GDBusProxy. - * @method_name: Name of method to invoke. - * @parameters: (nullable): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning - * "infinite") or -1 to use the proxy default timeout. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @callback: (nullable): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't - * care about the result of the method invocation. - * @user_data: The data to pass to @callback. - * - * Asynchronously invokes the @method_name method on @proxy. - * - * If @method_name contains any dots, then @name is split into interface and - * method name parts. This allows using @proxy for invoking methods on - * other interfaces. - * - * If the #GDBusConnection associated with @proxy is closed then - * the operation will fail with %G_IO_ERROR_CLOSED. If - * @cancellable is canceled, the operation will fail with - * %G_IO_ERROR_CANCELLED. If @parameters contains a value not - * compatible with the D-Bus protocol, the operation fails with - * %G_IO_ERROR_INVALID_ARGUMENT. - * - * If the @parameters #GVariant is floating, it is consumed. This allows - * convenient 'inline' use of g_variant_new(), e.g.: - * |[ - * g_dbus_proxy_call (proxy, - * "TwoStrings", - * g_variant_new ("(ss)", - * "Thing One", - * "Thing Two"), - * G_DBUS_CALL_FLAGS_NONE, - * -1, - * NULL, - * (GAsyncReadyCallback) two_strings_done, - * &data); - * ]| - * - * If @proxy has an expected interface (see - * #GDBusProxy:g-interface-info) and @method_name is referenced by it, - * then the return value is checked against the return type. - * - * This is an asynchronous method. When the operation is finished, - * @callback will be invoked in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread you are calling this method from. - * You can then call g_dbus_proxy_call_finish() to get the result of - * the operation. See g_dbus_proxy_call_sync() for the synchronous - * version of this method. - * - * If @callback is %NULL then the D-Bus method call message will be sent with - * the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. - * - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_call_finish: - * @proxy: A #GDBusProxy. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call(). - * @error: Return location for error or %NULL. - * - * Finishes an operation started with g_dbus_proxy_call(). - * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_call_sync: - * @proxy: A #GDBusProxy. - * @method_name: Name of method to invoke. - * @parameters: (nullable): A #GVariant tuple with parameters for the signal - * or %NULL if not passing parameters. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning - * "infinite") or -1 to use the proxy default timeout. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Synchronously invokes the @method_name method on @proxy. - * - * If @method_name contains any dots, then @name is split into interface and - * method name parts. This allows using @proxy for invoking methods on - * other interfaces. - * - * If the #GDBusConnection associated with @proxy is disconnected then - * the operation will fail with %G_IO_ERROR_CLOSED. If - * @cancellable is canceled, the operation will fail with - * %G_IO_ERROR_CANCELLED. If @parameters contains a value not - * compatible with the D-Bus protocol, the operation fails with - * %G_IO_ERROR_INVALID_ARGUMENT. - * - * If the @parameters #GVariant is floating, it is consumed. This allows - * convenient 'inline' use of g_variant_new(), e.g.: - * |[ - * g_dbus_proxy_call_sync (proxy, - * "TwoStrings", - * g_variant_new ("(ss)", - * "Thing One", - * "Thing Two"), - * G_DBUS_CALL_FLAGS_NONE, - * -1, - * NULL, - * &error); - * ]| - * - * The calling thread is blocked until a reply is received. See - * g_dbus_proxy_call() for the asynchronous version of this - * method. - * - * If @proxy has an expected interface (see - * #GDBusProxy:g-interface-info) and @method_name is referenced by it, - * then the return value is checked against the return type. - * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_call_with_unix_fd_list: - * @proxy: A #GDBusProxy. - * @method_name: Name of method to invoke. - * @parameters: (nullable): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning - * "infinite") or -1 to use the proxy default timeout. - * @fd_list: (nullable): A #GUnixFDList or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @callback: (nullable): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't - * care about the result of the method invocation. - * @user_data: The data to pass to @callback. - * - * Like g_dbus_proxy_call() but also takes a #GUnixFDList object. - * - * This method is only available on UNIX. - * - * Since: 2.30 - */ - - -/** - * g_dbus_proxy_call_with_unix_fd_list_finish: - * @proxy: A #GDBusProxy. - * @out_fd_list: (out) (optional): Return location for a #GUnixFDList or %NULL. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list(). - * @error: Return location for error or %NULL. - * - * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). - * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_proxy_call_with_unix_fd_list_sync: - * @proxy: A #GDBusProxy. - * @method_name: Name of method to invoke. - * @parameters: (nullable): A #GVariant tuple with parameters for the signal - * or %NULL if not passing parameters. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning - * "infinite") or -1 to use the proxy default timeout. - * @fd_list: (nullable): A #GUnixFDList or %NULL. - * @out_fd_list: (out) (optional): Return location for a #GUnixFDList or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Like g_dbus_proxy_call_sync() but also takes and returns #GUnixFDList objects. - * - * This method is only available on UNIX. - * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). - * Since: 2.30 - */ - - -/** - * g_dbus_proxy_get_cached_property: - * @proxy: A #GDBusProxy. - * @property_name: Property name. - * - * Looks up the value for a property from the cache. This call does no - * blocking IO. - * - * If @proxy has an expected interface (see - * #GDBusProxy:g-interface-info) and @property_name is referenced by - * it, then @value is checked against the type of the property. - * - * Returns: (transfer full) (nullable): A reference to the #GVariant instance - * that holds the value for @property_name or %NULL if the value is not in - * the cache. The returned reference must be freed with g_variant_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_get_cached_property_names: - * @proxy: A #GDBusProxy. - * - * Gets the names of all cached properties on @proxy. - * - * Returns: (transfer full) (nullable) (array zero-terminated=1): A - * %NULL-terminated array of strings or %NULL if - * @proxy has no cached properties. Free the returned array with - * g_strfreev(). - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_get_connection: - * @proxy: A #GDBusProxy. - * - * Gets the connection @proxy is for. - * - * Returns: (transfer none) (not nullable): A #GDBusConnection owned by @proxy. Do not free. - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_get_default_timeout: - * @proxy: A #GDBusProxy. - * - * Gets the timeout to use if -1 (specifying default timeout) is - * passed as @timeout_msec in the g_dbus_proxy_call() and - * g_dbus_proxy_call_sync() functions. - * - * See the #GDBusProxy:g-default-timeout property for more details. - * - * Returns: Timeout to use for @proxy. - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_get_flags: - * @proxy: A #GDBusProxy. - * - * Gets the flags that @proxy was constructed with. - * - * Returns: Flags from the #GDBusProxyFlags enumeration. - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_get_interface_info: - * @proxy: A #GDBusProxy - * - * Returns the #GDBusInterfaceInfo, if any, specifying the interface - * that @proxy conforms to. See the #GDBusProxy:g-interface-info - * property for more details. - * - * Returns: (transfer none) (nullable): A #GDBusInterfaceInfo or %NULL. - * Do not unref the returned object, it is owned by @proxy. - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_get_interface_name: - * @proxy: A #GDBusProxy. - * - * Gets the D-Bus interface name @proxy is for. - * - * Returns: (not nullable): A string owned by @proxy. Do not free. - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_get_name: - * @proxy: A #GDBusProxy. - * - * Gets the name that @proxy was constructed for. - * - * When connected to a message bus, this will usually be non-%NULL. - * However, it may be %NULL for a proxy that communicates using a peer-to-peer - * pattern. - * - * Returns: (nullable): A string owned by @proxy. Do not free. - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_get_name_owner: - * @proxy: A #GDBusProxy. - * - * The unique name that owns the name that @proxy is for or %NULL if - * no-one currently owns that name. You may connect to the - * #GObject::notify signal to track changes to the - * #GDBusProxy:g-name-owner property. - * - * Returns: (transfer full) (nullable): The name owner or %NULL if no name - * owner exists. Free with g_free(). - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_get_object_path: - * @proxy: A #GDBusProxy. - * - * Gets the object path @proxy is for. - * - * Returns: (not nullable): A string owned by @proxy. Do not free. - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_new: - * @connection: A #GDBusConnection. - * @flags: Flags used when constructing the proxy. - * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - * @name: (nullable): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. - * @object_path: An object path. - * @interface_name: A D-Bus interface name. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @callback: Callback function to invoke when the proxy is ready. - * @user_data: User data to pass to @callback. - * - * Creates a proxy for accessing @interface_name on the remote object - * at @object_path owned by @name at @connection and asynchronously - * loads D-Bus properties unless the - * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to - * the #GDBusProxy::g-properties-changed signal to get notified about - * property changes. - * - * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up - * match rules for signals. Connect to the #GDBusProxy::g-signal signal - * to handle signals from the remote object. - * - * If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and - * %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is - * guaranteed to complete immediately without blocking. - * - * If @name is a well-known name and the - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION - * flags aren't set and no name owner currently exists, the message bus - * will be requested to launch a name owner for the name. - * - * This is a failable asynchronous constructor - when the proxy is - * ready, @callback will be invoked and you can use - * g_dbus_proxy_new_finish() to get the result. - * - * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. - * - * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - * - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_new_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new(). - * @error: Return location for error or %NULL. - * - * Finishes creating a #GDBusProxy. - * - * Returns: (transfer full): A #GDBusProxy or %NULL if @error is set. - * Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_new_for_bus: - * @bus_type: A #GBusType. - * @flags: Flags used when constructing the proxy. - * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - * @name: A bus name (well-known or unique). - * @object_path: An object path. - * @interface_name: A D-Bus interface name. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @callback: Callback function to invoke when the proxy is ready. - * @user_data: User data to pass to @callback. - * - * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. - * - * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - * - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_new_for_bus_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus(). - * @error: Return location for error or %NULL. - * - * Finishes creating a #GDBusProxy. - * - * Returns: (transfer full): A #GDBusProxy or %NULL if @error is set. - * Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_new_for_bus_sync: - * @bus_type: A #GBusType. - * @flags: Flags used when constructing the proxy. - * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface - * that @proxy conforms to or %NULL. - * @name: A bus name (well-known or unique). - * @object_path: An object path. - * @interface_name: A D-Bus interface name. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. - * - * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - * - * Returns: (transfer full): A #GDBusProxy or %NULL if error is set. - * Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_new_sync: - * @connection: A #GDBusConnection. - * @flags: Flags used when constructing the proxy. - * @info: (nullable): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. - * @name: (nullable): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection. - * @object_path: An object path. - * @interface_name: A D-Bus interface name. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: (nullable): Return location for error or %NULL. - * - * Creates a proxy for accessing @interface_name on the remote object - * at @object_path owned by @name at @connection and synchronously - * loads D-Bus properties unless the - * %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. - * - * If the %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up - * match rules for signals. Connect to the #GDBusProxy::g-signal signal - * to handle signals from the remote object. - * - * If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and - * %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is - * guaranteed to return immediately without blocking. - * - * If @name is a well-known name and the - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION - * flags aren't set and no name owner currently exists, the message bus - * will be requested to launch a name owner for the name. - * - * This is a synchronous failable constructor. See g_dbus_proxy_new() - * and g_dbus_proxy_new_finish() for the asynchronous version. - * - * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. - * - * Returns: (transfer full): A #GDBusProxy or %NULL if error is set. - * Free with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_set_cached_property: - * @proxy: A #GDBusProxy - * @property_name: Property name. - * @value: (nullable): Value for the property or %NULL to remove it from the cache. - * - * If @value is not %NULL, sets the cached value for the property with - * name @property_name to the value in @value. - * - * If @value is %NULL, then the cached value is removed from the - * property cache. - * - * If @proxy has an expected interface (see - * #GDBusProxy:g-interface-info) and @property_name is referenced by - * it, then @value is checked against the type of the property. - * - * If the @value #GVariant is floating, it is consumed. This allows - * convenient 'inline' use of g_variant_new(), e.g. - * |[ - * g_dbus_proxy_set_cached_property (proxy, - * "SomeProperty", - * g_variant_new ("(si)", - * "A String", - * 42)); - * ]| - * - * Normally you will not need to use this method since @proxy - * is tracking changes using the - * `org.freedesktop.DBus.Properties.PropertiesChanged` - * D-Bus signal. However, for performance reasons an object may - * decide to not use this signal for some properties and instead - * use a proprietary out-of-band mechanism to transmit changes. - * - * As a concrete example, consider an object with a property - * `ChatroomParticipants` which is an array of strings. Instead of - * transmitting the same (long) array every time the property changes, - * it is more efficient to only transmit the delta using e.g. signals - * `ChatroomParticipantJoined(String name)` and - * `ChatroomParticipantParted(String name)`. - * - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_set_default_timeout: - * @proxy: A #GDBusProxy. - * @timeout_msec: Timeout in milliseconds. - * - * Sets the timeout to use if -1 (specifying default timeout) is - * passed as @timeout_msec in the g_dbus_proxy_call() and - * g_dbus_proxy_call_sync() functions. - * - * See the #GDBusProxy:g-default-timeout property for more details. - * - * Since: 2.26 - */ - - -/** - * g_dbus_proxy_set_interface_info: - * @proxy: A #GDBusProxy - * @info: (transfer none) (nullable): Minimum interface this proxy conforms to - * or %NULL to unset. - * - * Ensure that interactions with @proxy conform to the given - * interface. See the #GDBusProxy:g-interface-info property for more - * details. - * - * Since: 2.26 - */ - - -/** - * g_dbus_server_get_client_address: - * @server: A #GDBusServer. - * - * Gets a - * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) - * string that can be used by clients to connect to @server. - * - * This is valid and non-empty if initializing the #GDBusServer succeeded. - * - * Returns: (not nullable): A D-Bus address string. Do not free, the string is owned - * by @server. - * Since: 2.26 - */ - - -/** - * g_dbus_server_get_flags: - * @server: A #GDBusServer. - * - * Gets the flags for @server. - * - * Returns: A set of flags from the #GDBusServerFlags enumeration. - * Since: 2.26 - */ - - -/** - * g_dbus_server_get_guid: - * @server: A #GDBusServer. - * - * Gets the GUID for @server, as provided to g_dbus_server_new_sync(). - * - * Returns: (not nullable): A D-Bus GUID. Do not free this string, it is owned by @server. - * Since: 2.26 - */ - - -/** - * g_dbus_server_is_active: - * @server: A #GDBusServer. - * - * Gets whether @server is active. - * - * Returns: %TRUE if server is active, %FALSE otherwise. - * Since: 2.26 - */ - - -/** - * g_dbus_server_new_sync: - * @address: A D-Bus address. - * @flags: Flags from the #GDBusServerFlags enumeration. - * @guid: A D-Bus GUID. - * @observer: (nullable): A #GDBusAuthObserver or %NULL. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for server or %NULL. - * - * Creates a new D-Bus server that listens on the first address in - * @address that works. - * - * Once constructed, you can use g_dbus_server_get_client_address() to - * get a D-Bus address string that clients can use to connect. - * - * To have control over the available authentication mechanisms and - * the users that are authorized to connect, it is strongly recommended - * to provide a non-%NULL #GDBusAuthObserver. - * - * Connect to the #GDBusServer::new-connection signal to handle - * incoming connections. - * - * The returned #GDBusServer isn't active - you have to start it with - * g_dbus_server_start(). - * - * #GDBusServer is used in this [example][gdbus-peer-to-peer]. - * - * This is a synchronous failable constructor. There is currently no - * asynchronous version. - * - * Returns: A #GDBusServer or %NULL if @error is set. Free with - * g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_dbus_server_start: - * @server: A #GDBusServer. - * - * Starts @server. - * - * Since: 2.26 - */ - - -/** - * g_dbus_server_stop: - * @server: A #GDBusServer. - * - * Stops @server. - * - * Since: 2.26 - */ - - -/** - * g_dbus_signal_info_ref: - * @info: A #GDBusSignalInfo - * - * If @info is statically allocated does nothing. Otherwise increases - * the reference count. - * - * Returns: (not nullable): The same @info. - * Since: 2.26 - */ - - -/** - * g_dbus_signal_info_unref: - * @info: A #GDBusSignalInfo. - * - * If @info is statically allocated, does nothing. Otherwise decreases - * the reference count of @info. When its reference count drops to 0, - * the memory used is freed. - * - * Since: 2.26 - */ - - -/** - * g_dbus_unescape_object_path: - * @s: the string to unescape - * - * Unescapes an string that was previously escaped with - * g_dbus_escape_object_path(). If the string is in a format that could - * not have been returned by g_dbus_escape_object_path(), this function - * returns %NULL. - * - * Encoding alphanumeric characters which do not need to be - * encoded is not allowed (e.g `_63` is not valid, the string - * should contain `c` instead). - * - * Returns: (array zero-terminated=1) (element-type guint8) (nullable): an - * unescaped version of @s, or %NULL if @s is not a string returned - * from g_dbus_escape_object_path(). Free with g_free(). - * Since: 2.68 - */ - - -/** - * 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 - * - * Gets the categories from the desktop file. - * - * Returns: (nullable): The unparsed Categories key from the desktop file; - * i.e. no attempt is made to split it by ';' or validate it. - */ - - -/** - * g_desktop_app_info_get_filename: - * @info: a #GDesktopAppInfo - * - * When @info was created from a known filename, return it. In some - * situations such as the #GDesktopAppInfo returned from - * g_desktop_app_info_new_from_keyfile(), this function will return %NULL. - * - * Returns: (nullable) (type filename): The full path to the file for @info, - * or %NULL if not known. - * Since: 2.24 - */ - - -/** - * g_desktop_app_info_get_generic_name: - * @info: a #GDesktopAppInfo - * - * Gets the generic name from the desktop file. - * - * Returns: (nullable): The value of the GenericName key - */ - - -/** - * g_desktop_app_info_get_implementations: - * @interface: the name of the interface - * - * Gets all applications that implement @interface. - * - * An application implements an interface if that interface is listed in - * the Implements= line of the desktop file of the application. - * - * Returns: (element-type GDesktopAppInfo) (transfer full): a list of #GDesktopAppInfo - * objects. - * Since: 2.42 - */ - - -/** - * g_desktop_app_info_get_is_hidden: - * @info: a #GDesktopAppInfo. - * - * A desktop file is hidden if the Hidden key in it is - * set to True. - * - * Returns: %TRUE if hidden, %FALSE otherwise. - */ - - -/** - * g_desktop_app_info_get_keywords: - * @info: a #GDesktopAppInfo - * - * Gets the keywords from the desktop file. - * - * Returns: (transfer none): The value of the Keywords key - * Since: 2.32 - */ - - -/** - * g_desktop_app_info_get_locale_string: - * @info: a #GDesktopAppInfo - * @key: the key to look up - * - * Looks up a localized string value in the keyfile backing @info - * translated to the current locale. - * - * The @key is looked up in the "Desktop Entry" group. - * - * Returns: (nullable): a newly allocated string, or %NULL if the key - * is not found - * Since: 2.56 - */ - - -/** - * g_desktop_app_info_get_nodisplay: - * @info: a #GDesktopAppInfo - * - * Gets the value of the NoDisplay key, which helps determine if the - * application info should be shown in menus. See - * #G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show(). - * - * Returns: The value of the NoDisplay key - * Since: 2.30 - */ - - -/** - * g_desktop_app_info_get_show_in: - * @info: a #GDesktopAppInfo - * @desktop_env: (nullable): a string specifying a desktop name - * - * Checks if the application info should be shown in menus that list available - * applications for a specific name of the desktop, based on the - * `OnlyShowIn` and `NotShowIn` keys. - * - * @desktop_env should typically be given as %NULL, in which case the - * `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want - * to override the default mechanism then you may specify @desktop_env, - * but this is not recommended. - * - * Note that g_app_info_should_show() for @info will include this check (with - * %NULL for @desktop_env) as well as additional checks. - * - * Returns: %TRUE if the @info should be shown in @desktop_env according to the - * `OnlyShowIn` and `NotShowIn` keys, %FALSE - * otherwise. - * Since: 2.30 - */ - - -/** - * g_desktop_app_info_get_startup_wm_class: - * @info: a #GDesktopAppInfo that supports startup notify - * - * Retrieves the StartupWMClass field from @info. This represents the - * WM_CLASS property of the main window of the application, if launched - * through @info. - * - * Returns: (nullable) (transfer none): the startup WM class, or %NULL if none is set - * in the desktop file. - * Since: 2.34 - */ - - -/** - * 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: (nullable): a newly allocated string, or %NULL if the key - * is not found - * Since: 2.36 - */ - - -/** - * g_desktop_app_info_get_string_list: - * @info: a #GDesktopAppInfo - * @key: the key to look up - * @length: (out) (optional): return location for the number of returned strings, or %NULL - * - * Looks up a string list value in the keyfile backing @info. - * - * The @key is looked up in the "Desktop Entry" group. - * - * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): - * a %NULL-terminated string array or %NULL if the specified - * key cannot be found. The array should be freed with g_strfreev(). - * Since: 2.60 - */ - - -/** - * 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.36 - */ - - -/** - * 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: (nullable): 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 - * @launch_context: (nullable): a #GAppLaunchContext - * @spawn_flags: #GSpawnFlags, used for each process - * @user_setup: (scope async) (nullable): a #GSpawnChildSetupFunc, used once - * for each process. - * @user_setup_data: (closure user_setup) (nullable): User data for @user_setup - * @pid_callback: (scope call) (nullable): Callback for child processes - * @pid_callback_data: (closure pid_callback) (nullable): User data for @callback - * @error: return location for a #GError, or %NULL - * - * This function performs the equivalent of g_app_info_launch_uris(), - * but is intended primarily for operating system components that - * launch applications. Ordinary applications should use - * g_app_info_launch_uris(). - * - * If the application is launched via GSpawn, 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. See g_spawn_async_with_pipes() - * for information on certain parameter conditions that can enable an - * optimized posix_spawn() codepath to be used. - * - * 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_launch_uris_as_manager_with_fds: - * @appinfo: a #GDesktopAppInfo - * @uris: (element-type utf8): List of URIs - * @launch_context: (nullable): a #GAppLaunchContext - * @spawn_flags: #GSpawnFlags, used for each process - * @user_setup: (scope async) (nullable): a #GSpawnChildSetupFunc, used once - * for each process. - * @user_setup_data: (closure user_setup) (nullable): User data for @user_setup - * @pid_callback: (scope call) (nullable): Callback for child processes - * @pid_callback_data: (closure pid_callback) (nullable): User data for @callback - * @stdin_fd: file descriptor to use for child's stdin, or -1 - * @stdout_fd: file descriptor to use for child's stdout, or -1 - * @stderr_fd: file descriptor to use for child's stderr, or -1 - * @error: return location for a #GError, or %NULL - * - * Equivalent to g_desktop_app_info_launch_uris_as_manager() but allows - * you to pass in file descriptors for the stdin, stdout and stderr streams - * of the launched process. - * - * If application launching occurs via some non-spawn mechanism (e.g. D-Bus - * activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. - * - * Returns: %TRUE on successful launch, %FALSE otherwise. - * Since: 2.58 - */ - - -/** - * 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. - * - * Gets the default application for launching applications - * using this URI scheme for a particular #GDesktopAppInfoLookup - * implementation. - * - * The #GDesktopAppInfoLookup interface and this function is used - * to implement g_app_info_get_default_for_uri_scheme() backends - * in a GIO module. There is no reason for applications to use it - * directly. Applications should use g_app_info_get_default_for_uri_scheme(). - * - * Returns: (transfer full) (nullable): #GAppInfo for given @uri_scheme or - * %NULL on error. - * Deprecated: 2.28: The #GDesktopAppInfoLookup interface is deprecated and - * unused by GIO. - */ - - -/** - * g_desktop_app_info_new: - * @desktop_id: the desktop file id - * - * Creates a new #GDesktopAppInfo based on a desktop file id. - * - * A desktop file id is the basename of the desktop file, including the - * .desktop extension. GIO is looking for a desktop file with this name - * in the `applications` subdirectories of the XDG - * data directories (i.e. the directories specified in the `XDG_DATA_HOME` - * and `XDG_DATA_DIRS` environment variables). GIO also supports the - * prefix-to-subdirectory mapping that is described in the - * [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/) - * (i.e. a desktop id of kde-foo.desktop will match - * `/usr/share/applications/kde/foo.desktop`). - * - * Returns: (nullable): a new #GDesktopAppInfo, or %NULL if no desktop - * file with that id exists. - */ - - -/** - * g_desktop_app_info_new_from_filename: - * @filename: (type filename): the path of a desktop file, in the GLib - * filename encoding - * - * Creates a new #GDesktopAppInfo. - * - * Returns: (nullable): a new #GDesktopAppInfo or %NULL on error. - */ - - -/** - * g_desktop_app_info_new_from_keyfile: - * @key_file: an opened #GKeyFile - * - * Creates a new #GDesktopAppInfo. - * - * Returns: (nullable): a new #GDesktopAppInfo or %NULL on error. - * Since: 2.18 - */ - - -/** - * g_desktop_app_info_search: - * @search_string: the search string to use - * - * Searches desktop files for ones that match @search_string. - * - * The return value is an array of strvs. Each strv contains a list of - * applications that matched @search_string with an equal score. The - * outer list is sorted by score so that the first strv contains the - * best-matching applications, and so on. - * The algorithm for determining matches is undefined and may change at - * any time. - * - * None of the search results are subjected to the normal validation - * checks performed by g_desktop_app_info_new() (for example, checking that - * the executable referenced by a result exists), and so it is possible for - * g_desktop_app_info_new() to return %NULL when passed an app ID returned by - * this function. It is expected that calling code will do this when - * subsequently creating a #GDesktopAppInfo for each result. - * - * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a - * list of strvs. Free each item with g_strfreev() and free the outer - * list with g_free(). - */ - - -/** - * g_desktop_app_info_set_desktop_env: - * @desktop_env: a string specifying what desktop this is - * - * Sets the name of the desktop that the application is running in. - * This is used by g_app_info_should_show() and - * g_desktop_app_info_get_show_in() to evaluate the - * `OnlyShowIn` and `NotShowIn` - * desktop entry fields. - * - * Should be called only once; subsequent calls are ignored. - * - * Deprecated: 2.42: do not use this API. Since 2.42 the value of the - * `XDG_CURRENT_DESKTOP` environment variable will be used. - */ - - -/** - * g_drive_can_eject: - * @drive: a #GDrive. - * - * Checks if a drive can be ejected. - * - * Returns: %TRUE if the @drive can be ejected, %FALSE otherwise. - */ - - -/** - * g_drive_can_poll_for_media: - * @drive: a #GDrive. - * - * Checks if a drive can be polled for media changes. - * - * Returns: %TRUE if the @drive can be polled for media changes, - * %FALSE otherwise. - */ - - -/** - * g_drive_can_start: - * @drive: a #GDrive. - * - * Checks if a drive can be started. - * - * Returns: %TRUE if the @drive can be started, %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_drive_can_start_degraded: - * @drive: a #GDrive. - * - * Checks if a drive can be started degraded. - * - * Returns: %TRUE if the @drive can be started degraded, %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_drive_can_stop: - * @drive: a #GDrive. - * - * Checks if a drive can be stopped. - * - * Returns: %TRUE if the @drive can be stopped, %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_drive_eject: - * @drive: a #GDrive. - * @flags: flags affecting the unmount if required for eject - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback - * - * Asynchronously ejects a drive. - * - * When the operation is finished, @callback will be called. - * You can then call g_drive_eject_finish() to obtain the - * result of the operation. - * - * Deprecated: 2.22: Use g_drive_eject_with_operation() instead. - */ - - -/** - * g_drive_eject_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes ejecting a drive. - * - * Returns: %TRUE if the drive has been ejected successfully, - * %FALSE otherwise. - * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead. - */ - - -/** - * g_drive_eject_with_operation: - * @drive: a #GDrive. - * @flags: flags affecting the unmount if required for eject - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. - * - * Ejects a drive. This is an asynchronous operation, and is - * finished by calling g_drive_eject_with_operation_finish() with the @drive - * and #GAsyncResult data returned in the @callback. - * - * Since: 2.22 - */ - - -/** - * g_drive_eject_with_operation_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes ejecting a drive. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. - * - * Returns: %TRUE if the drive was successfully ejected. %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_drive_enumerate_identifiers: - * @drive: a #GDrive - * - * Gets the kinds of identifiers that @drive has. - * Use g_drive_get_identifier() to obtain the identifiers - * themselves. - * - * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated - * array of strings containing kinds of identifiers. Use g_strfreev() - * to free. - */ - - -/** - * g_drive_get_icon: - * @drive: a #GDrive. - * - * Gets the icon for @drive. - * - * Returns: (transfer full): #GIcon for the @drive. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_drive_get_identifier: - * @drive: a #GDrive - * @kind: the kind of identifier to return - * - * Gets the identifier of the given kind for @drive. The only - * identifier currently available is - * #G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE. - * - * Returns: (nullable) (transfer full): a newly allocated string containing the - * requested identifier, or %NULL if the #GDrive - * doesn't have this kind of identifier. - */ - - -/** - * g_drive_get_name: - * @drive: a #GDrive. - * - * Gets the name of @drive. - * - * Returns: a string containing @drive's name. The returned - * string should be freed when no longer needed. - */ - - -/** - * g_drive_get_sort_key: - * @drive: A #GDrive. - * - * Gets the sort key for @drive, if any. - * - * Returns: (nullable): Sorting key for @drive or %NULL if no such key is available. - * Since: 2.32 - */ - - -/** - * g_drive_get_start_stop_type: - * @drive: a #GDrive. - * - * Gets a hint about how a drive can be started/stopped. - * - * Returns: A value from the #GDriveStartStopType enumeration. - * Since: 2.22 - */ - - -/** - * g_drive_get_symbolic_icon: - * @drive: a #GDrive. - * - * Gets the icon for @drive. - * - * Returns: (transfer full): symbolic #GIcon for the @drive. - * Free the returned object with g_object_unref(). - * Since: 2.34 - */ - - -/** - * g_drive_get_volumes: - * @drive: a #GDrive. - * - * Get a list of mountable volumes for @drive. - * - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). - * - * Returns: (element-type GVolume) (transfer full): #GList containing any #GVolume objects on the given @drive. - */ - - -/** - * g_drive_has_media: - * @drive: a #GDrive. - * - * Checks if the @drive has media. Note that the OS may not be polling - * the drive for media changes; see g_drive_is_media_check_automatic() - * for more details. - * - * Returns: %TRUE if @drive has media, %FALSE otherwise. - */ - - -/** - * g_drive_has_volumes: - * @drive: a #GDrive. - * - * Check if @drive has any mountable volumes. - * - * Returns: %TRUE if the @drive contains volumes, %FALSE otherwise. - */ - - -/** - * g_drive_is_media_check_automatic: - * @drive: a #GDrive. - * - * Checks if @drive is capable of automatically detecting media changes. - * - * Returns: %TRUE if the @drive is capable of automatically detecting - * media changes, %FALSE otherwise. - */ - - -/** - * g_drive_is_media_removable: - * @drive: a #GDrive. - * - * Checks if the @drive supports removable media. - * - * Returns: %TRUE if @drive supports removable media, %FALSE otherwise. - */ - - -/** - * g_drive_is_removable: - * @drive: a #GDrive. - * - * Checks if the #GDrive and/or its media is considered removable by the user. - * See g_drive_is_media_removable(). - * - * Returns: %TRUE if @drive and/or its media is considered removable, %FALSE otherwise. - * Since: 2.50 - */ - - -/** - * g_drive_poll_for_media: - * @drive: a #GDrive. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback - * - * Asynchronously polls @drive to see if media has been inserted or removed. - * - * When the operation is finished, @callback will be called. - * You can then call g_drive_poll_for_media_finish() to obtain the - * result of the operation. - */ - - -/** - * g_drive_poll_for_media_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes an operation started with g_drive_poll_for_media() on a drive. - * - * Returns: %TRUE if the drive has been poll_for_mediaed successfully, - * %FALSE otherwise. - */ - - -/** - * g_drive_start: - * @drive: a #GDrive. - * @flags: flags affecting the start operation. - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback - * - * Asynchronously starts a drive. - * - * When the operation is finished, @callback will be called. - * You can then call g_drive_start_finish() to obtain the - * result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_drive_start_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes starting a drive. - * - * Returns: %TRUE if the drive has been started successfully, - * %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_drive_stop: - * @drive: a #GDrive. - * @flags: flags affecting the unmount if required for stopping. - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data to pass to @callback - * - * Asynchronously stops a drive. - * - * When the operation is finished, @callback will be called. - * You can then call g_drive_stop_finish() to obtain the - * result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_drive_stop_finish: - * @drive: a #GDrive. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes stopping a drive. - * - * Returns: %TRUE if the drive has been stopped successfully, - * %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_dtls_client_connection_get_accepted_cas: - * @conn: the #GDtlsClientConnection - * - * Gets the list of distinguished names of the Certificate Authorities - * that the server will accept certificates from. This will be set - * during the TLS handshake if the server requests a certificate. - * Otherwise, it will be %NULL. - * - * Each item in the list is a #GByteArray which contains the complete - * subject DN of the certificate authority. - * - * Returns: (element-type GByteArray) (transfer full): the list of - * CA DNs. You should unref each element with g_byte_array_unref() and then - * the free the list with g_list_free(). - * Since: 2.48 - */ - - -/** - * g_dtls_client_connection_get_server_identity: - * @conn: the #GDtlsClientConnection - * - * Gets @conn's expected server identity - * - * Returns: (transfer none): a #GSocketConnectable describing the - * expected server identity, or %NULL if the expected identity is not - * known. - * Since: 2.48 - */ - - -/** - * g_dtls_client_connection_get_validation_flags: - * @conn: the #GDtlsClientConnection - * - * Gets @conn's validation flags - * - * Returns: the validation flags - * Since: 2.48 - */ - - -/** - * g_dtls_client_connection_new: - * @base_socket: the #GDatagramBased to wrap - * @server_identity: (nullable): the expected identity of the server - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a new #GDtlsClientConnection wrapping @base_socket which is - * assumed to communicate with the server identified by @server_identity. - * - * Returns: (transfer full) (type GDtlsClientConnection): the new - * #GDtlsClientConnection, or %NULL on error - * Since: 2.48 - */ - - -/** - * g_dtls_client_connection_set_server_identity: - * @conn: the #GDtlsClientConnection - * @identity: a #GSocketConnectable describing the expected server identity - * - * Sets @conn's expected server identity, which is used both to tell - * servers on virtual hosts which certificate to present, and also - * to let @conn know what name to look for in the certificate when - * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. - * - * Since: 2.48 - */ - - -/** - * g_dtls_client_connection_set_validation_flags: - * @conn: the #GDtlsClientConnection - * @flags: the #GTlsCertificateFlags to use - * - * Sets @conn's validation flags, to override the default set of - * checks performed when validating a server certificate. By default, - * %G_TLS_CERTIFICATE_VALIDATE_ALL is used. - * - * Since: 2.48 - */ - - -/** - * g_dtls_connection_close: - * @conn: a #GDtlsConnection - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError, or %NULL - * - * Close the DTLS connection. This is equivalent to calling - * g_dtls_connection_shutdown() to shut down both sides of the connection. - * - * Closing a #GDtlsConnection waits for all buffered but untransmitted data to - * be sent before it completes. It then sends a `close_notify` DTLS alert to the - * peer and may wait for a `close_notify` to be received from the peer. It does - * not close the underlying #GDtlsConnection:base-socket; that must be closed - * separately. - * - * Once @conn is closed, all other operations will return %G_IO_ERROR_CLOSED. - * Closing a #GDtlsConnection multiple times will not return an error. - * - * #GDtlsConnections will be automatically closed when the last reference is - * dropped, but you might want to call this function to make sure resources are - * released as early as possible. - * - * If @cancellable is cancelled, the #GDtlsConnection may be left - * partially-closed and any pending untransmitted data may be lost. Call - * g_dtls_connection_close() again to complete closing the #GDtlsConnection. - * - * Returns: %TRUE on success, %FALSE otherwise - * Since: 2.48 - */ - - -/** - * g_dtls_connection_close_async: - * @conn: a #GDtlsConnection - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the close operation is complete - * @user_data: the data to pass to the callback function - * - * Asynchronously close the DTLS connection. See g_dtls_connection_close() for - * more information. - * - * Since: 2.48 - */ - - -/** - * g_dtls_connection_close_finish: - * @conn: a #GDtlsConnection - * @result: a #GAsyncResult - * @error: a #GError pointer, or %NULL - * - * Finish an asynchronous TLS close operation. See g_dtls_connection_close() - * for more information. - * - * Returns: %TRUE on success, %FALSE on failure, in which - * case @error will be set - * Since: 2.48 - */ - - -/** - * g_dtls_connection_emit_accept_certificate: - * @conn: a #GDtlsConnection - * @peer_cert: the peer's #GTlsCertificate - * @errors: the problems with @peer_cert - * - * Used by #GDtlsConnection implementations to emit the - * #GDtlsConnection::accept-certificate signal. - * - * Returns: %TRUE if one of the signal handlers has returned - * %TRUE to accept @peer_cert - * Since: 2.48 - */ - - -/** - * g_dtls_connection_get_certificate: - * @conn: a #GDtlsConnection - * - * Gets @conn's certificate, as set by - * g_dtls_connection_set_certificate(). - * - * Returns: (transfer none) (nullable): @conn's certificate, or %NULL - * Since: 2.48 - */ - - -/** - * g_dtls_connection_get_channel_binding_data: - * @conn: a #GDtlsConnection - * @type: #GTlsChannelBindingType type of data to fetch - * @data: (out callee-allocates) (optional) (transfer none): #GByteArray is - * filled with the binding data, or %NULL - * @error: a #GError pointer, or %NULL - * - * Query the TLS backend for TLS channel binding data of @type for @conn. - * - * This call retrieves TLS channel binding data as specified in RFC - * [5056](https://tools.ietf.org/html/rfc5056), RFC - * [5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The - * binding data is returned in @data. The @data is resized by the callee - * using #GByteArray buffer management and will be freed when the @data - * is destroyed by g_byte_array_unref(). If @data is %NULL, it will only - * check whether TLS backend is able to fetch the data (e.g. whether @type - * is supported by the TLS backend). It does not guarantee that the data - * will be available though. That could happen if TLS connection does not - * support @type or the binding data is not available yet due to additional - * negotiation or input required. - * - * Returns: %TRUE on success, %FALSE otherwise - * Since: 2.66 - */ - - -/** - * g_dtls_connection_get_ciphersuite_name: - * @conn: a #GDTlsConnection - * - * Returns the name of the current DTLS ciphersuite, or %NULL if the - * connection has not handshaked or has been closed. Beware that the TLS - * backend may use any of multiple different naming conventions, because - * OpenSSL and GnuTLS have their own ciphersuite naming conventions that - * are different from each other and different from the standard, IANA- - * registered ciphersuite names. The ciphersuite name is intended to be - * displayed to the user for informative purposes only, and parsing it - * is not recommended. - * - * Returns: (nullable): The name of the current DTLS ciphersuite, or %NULL - * Since: 2.70 - */ - - -/** - * g_dtls_connection_get_database: - * @conn: a #GDtlsConnection - * - * Gets the certificate database that @conn uses to verify - * peer certificates. See g_dtls_connection_set_database(). - * - * Returns: (transfer none) (nullable): the certificate database that @conn uses or %NULL - * Since: 2.48 - */ - - -/** - * g_dtls_connection_get_interaction: - * @conn: a connection - * - * Get the object that will be used to interact with the user. It will be used - * for things like prompting the user for passwords. If %NULL is returned, then - * no user interaction will occur for this connection. - * - * Returns: (transfer none) (nullable): The interaction object. - * Since: 2.48 - */ - - -/** - * g_dtls_connection_get_negotiated_protocol: - * @conn: a #GDtlsConnection - * - * Gets the name of the application-layer protocol negotiated during - * the handshake. - * - * If the peer did not use the ALPN extension, or did not advertise a - * protocol that matched one of @conn's protocols, or the TLS backend - * does not support ALPN, then this will be %NULL. See - * g_dtls_connection_set_advertised_protocols(). - * - * Returns: (nullable): the negotiated protocol, or %NULL - * Since: 2.60 - */ - - -/** - * g_dtls_connection_get_peer_certificate: - * @conn: a #GDtlsConnection - * - * Gets @conn's peer's certificate after the handshake has completed - * or failed. (It is not set during the emission of - * #GDtlsConnection::accept-certificate.) - * - * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL - * Since: 2.48 - */ - - -/** - * g_dtls_connection_get_peer_certificate_errors: - * @conn: a #GDtlsConnection - * - * Gets the errors associated with validating @conn's peer's - * certificate, after the handshake has completed or failed. (It is - * not set during the emission of #GDtlsConnection::accept-certificate.) - * - * Returns: @conn's peer's certificate errors - * Since: 2.48 - */ - - -/** - * g_dtls_connection_get_protocol_version: - * @conn: a #GDTlsConnection - * - * Returns the current DTLS protocol version, which may be - * %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or - * has been closed, or if the TLS backend has implemented a protocol version - * that is not a recognized #GTlsProtocolVersion. - * - * Returns: The current DTLS protocol version - * Since: 2.70 - */ - - -/** - * g_dtls_connection_get_rehandshake_mode: - * @conn: a #GDtlsConnection - * - * Gets @conn rehandshaking mode. See - * g_dtls_connection_set_rehandshake_mode() for details. - * - * Returns: %G_TLS_REHANDSHAKE_SAFELY - * Since: 2.48 - * Deprecated: 2.64.: Changing the rehandshake mode is no longer - * required for compatibility. Also, rehandshaking has been removed - * from the TLS protocol in TLS 1.3. - */ - - -/** - * g_dtls_connection_get_require_close_notify: - * @conn: a #GDtlsConnection - * - * Tests whether or not @conn expects a proper TLS close notification - * when the connection is closed. See - * g_dtls_connection_set_require_close_notify() for details. - * - * Returns: %TRUE if @conn requires a proper TLS close notification. - * Since: 2.48 - */ - - -/** - * g_dtls_connection_handshake: - * @conn: a #GDtlsConnection - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError, or %NULL - * - * Attempts a TLS handshake on @conn. - * - * On the client side, it is never necessary to call this method; - * although the connection needs to perform a handshake after - * connecting, #GDtlsConnection will handle this for you automatically - * when you try to send or receive data on the connection. You can call - * g_dtls_connection_handshake() manually if you want to know whether - * the initial handshake succeeded or failed (as opposed to just - * immediately trying to use @conn to read or write, in which case, - * if it fails, it may not be possible to tell if it failed before - * or after completing the handshake), but beware that servers may reject - * client authentication after the handshake has completed, so a - * successful handshake does not indicate the connection will be usable. - * - * Likewise, on the server side, although a handshake is necessary at - * the beginning of the communication, you do not need to call this - * function explicitly unless you want clearer error reporting. - * - * Previously, calling g_dtls_connection_handshake() after the initial - * handshake would trigger a rehandshake; however, this usage was - * deprecated in GLib 2.60 because rehandshaking was removed from the - * TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after - * the initial handshake will no longer do anything. - * - * #GDtlsConnection::accept_certificate may be emitted during the - * handshake. - * - * Returns: success or failure - * Since: 2.48 - */ - - -/** - * g_dtls_connection_handshake_async: - * @conn: a #GDtlsConnection - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the handshake is complete - * @user_data: the data to pass to the callback function - * - * Asynchronously performs a TLS handshake on @conn. See - * g_dtls_connection_handshake() for more information. - * - * Since: 2.48 - */ - - -/** - * g_dtls_connection_handshake_finish: - * @conn: a #GDtlsConnection - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL - * - * Finish an asynchronous TLS handshake operation. See - * g_dtls_connection_handshake() for more information. - * - * Returns: %TRUE on success, %FALSE on failure, in which - * case @error will be set. - * Since: 2.48 - */ - - -/** - * g_dtls_connection_set_advertised_protocols: - * @conn: a #GDtlsConnection - * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated - * array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL - * - * Sets the list of application-layer protocols to advertise that the - * caller is willing to speak on this connection. The - * Application-Layer Protocol Negotiation (ALPN) extension will be - * used to negotiate a compatible protocol with the peer; use - * g_dtls_connection_get_negotiated_protocol() to find the negotiated - * protocol after the handshake. Specifying %NULL for the the value - * of @protocols will disable ALPN negotiation. - * - * See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) - * for a list of registered protocol IDs. - * - * Since: 2.60 - */ - - -/** - * g_dtls_connection_set_certificate: - * @conn: a #GDtlsConnection - * @certificate: the certificate to use for @conn - * - * This sets the certificate that @conn will present to its peer - * during the TLS handshake. For a #GDtlsServerConnection, it is - * mandatory to set this, and that will normally be done at construct - * time. - * - * For a #GDtlsClientConnection, this is optional. If a handshake fails - * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server - * requires a certificate, and if you try connecting again, you should - * call this method first. You can call - * g_dtls_client_connection_get_accepted_cas() on the failed connection - * to get a list of Certificate Authorities that the server will - * accept certificates from. - * - * (It is also possible that a server will allow the connection with - * or without a certificate; in that case, if you don't provide a - * certificate, you can tell that the server requested one by the fact - * that g_dtls_client_connection_get_accepted_cas() will return - * non-%NULL.) - * - * Since: 2.48 - */ - - -/** - * g_dtls_connection_set_database: - * @conn: a #GDtlsConnection - * @database: (nullable): a #GTlsDatabase - * - * Sets the certificate database that is used to verify peer certificates. - * This is set to the default database by default. See - * g_tls_backend_get_default_database(). If set to %NULL, then - * peer certificate validation will always set the - * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning - * #GDtlsConnection::accept-certificate will always be emitted on - * client-side connections, unless that bit is not set in - * #GDtlsClientConnection:validation-flags). - * - * Since: 2.48 - */ - - -/** - * g_dtls_connection_set_interaction: - * @conn: a connection - * @interaction: (nullable): an interaction object, or %NULL - * - * Set the object that will be used to interact with the user. It will be used - * for things like prompting the user for passwords. - * - * The @interaction argument will normally be a derived subclass of - * #GTlsInteraction. %NULL can also be provided if no user interaction - * should occur for this connection. - * - * Since: 2.48 - */ - - -/** - * g_dtls_connection_set_rehandshake_mode: - * @conn: a #GDtlsConnection - * @mode: the rehandshaking mode - * - * Since GLib 2.64, changing the rehandshake mode is no longer supported - * and will have no effect. With TLS 1.3, rehandshaking has been removed from - * the TLS protocol, replaced by separate post-handshake authentication and - * rekey operations. - * - * Since: 2.48 - * Deprecated: 2.60.: Changing the rehandshake mode is no longer - * required for compatibility. Also, rehandshaking has been removed - * from the TLS protocol in TLS 1.3. - */ - - -/** - * g_dtls_connection_set_require_close_notify: - * @conn: a #GDtlsConnection - * @require_close_notify: whether or not to require close notification - * - * Sets whether or not @conn expects a proper TLS close notification - * before the connection is closed. If this is %TRUE (the default), - * then @conn will expect to receive a TLS close notification from its - * peer before the connection is closed, and will return a - * %G_TLS_ERROR_EOF error if the connection is closed without proper - * notification (since this may indicate a network error, or - * man-in-the-middle attack). - * - * In some protocols, the application will know whether or not the - * connection was closed cleanly based on application-level data - * (because the application-level data includes a length field, or is - * somehow self-delimiting); in this case, the close notify is - * redundant and may be omitted. You - * can use g_dtls_connection_set_require_close_notify() to tell @conn - * to allow an "unannounced" connection close, in which case the close - * will show up as a 0-length read, as in a non-TLS - * #GDatagramBased, and it is up to the application to check that - * the data has been fully received. - * - * Note that this only affects the behavior when the peer closes the - * connection; when the application calls g_dtls_connection_close_async() on - * @conn itself, this will send a close notification regardless of the - * setting of this property. If you explicitly want to do an unclean - * close, you can close @conn's #GDtlsConnection:base-socket rather - * than closing @conn itself. - * - * Since: 2.48 - */ - - -/** - * g_dtls_connection_shutdown: - * @conn: a #GDtlsConnection - * @shutdown_read: %TRUE to stop reception of incoming datagrams - * @shutdown_write: %TRUE to stop sending outgoing datagrams - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError, or %NULL - * - * Shut down part or all of a DTLS connection. - * - * If @shutdown_read is %TRUE then the receiving side of the connection is shut - * down, and further reading is disallowed. Subsequent calls to - * g_datagram_based_receive_messages() will return %G_IO_ERROR_CLOSED. - * - * If @shutdown_write is %TRUE then the sending side of the connection is shut - * down, and further writing is disallowed. Subsequent calls to - * g_datagram_based_send_messages() will return %G_IO_ERROR_CLOSED. - * - * It is allowed for both @shutdown_read and @shutdown_write to be TRUE — this - * is equivalent to calling g_dtls_connection_close(). - * - * If @cancellable is cancelled, the #GDtlsConnection may be left - * partially-closed and any pending untransmitted data may be lost. Call - * g_dtls_connection_shutdown() again to complete closing the #GDtlsConnection. - * - * Returns: %TRUE on success, %FALSE otherwise - * Since: 2.48 - */ - - -/** - * g_dtls_connection_shutdown_async: - * @conn: a #GDtlsConnection - * @shutdown_read: %TRUE to stop reception of incoming datagrams - * @shutdown_write: %TRUE to stop sending outgoing datagrams - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the shutdown operation is complete - * @user_data: the data to pass to the callback function - * - * Asynchronously shut down part or all of the DTLS connection. See - * g_dtls_connection_shutdown() for more information. - * - * Since: 2.48 - */ - - -/** - * g_dtls_connection_shutdown_finish: - * @conn: a #GDtlsConnection - * @result: a #GAsyncResult - * @error: a #GError pointer, or %NULL - * - * Finish an asynchronous TLS shutdown operation. See - * g_dtls_connection_shutdown() for more information. - * - * Returns: %TRUE on success, %FALSE on failure, in which - * case @error will be set - * Since: 2.48 - */ - - -/** - * g_dtls_server_connection_new: - * @base_socket: the #GDatagramBased to wrap - * @certificate: (nullable): the default server certificate, or %NULL - * @error: #GError for error reporting, or %NULL to ignore - * - * Creates a new #GDtlsServerConnection wrapping @base_socket. - * - * Returns: (transfer full) (type GDtlsServerConnection): the new - * #GDtlsServerConnection, or %NULL on error - * Since: 2.48 - */ - - -/** - * g_emblem_get_icon: - * @emblem: a #GEmblem from which the icon should be extracted. - * - * Gives back the icon from @emblem. - * - * Returns: (transfer none): a #GIcon. The returned object belongs to - * the emblem and should not be modified or freed. - * Since: 2.18 - */ - - -/** - * g_emblem_get_origin: - * @emblem: a #GEmblem - * - * Gets the origin of the emblem. - * - * Returns: (transfer none): the origin of the emblem - * Since: 2.18 - */ - - -/** - * g_emblem_new: - * @icon: a GIcon containing the icon. - * - * Creates a new emblem for @icon. - * - * Returns: a new #GEmblem. - * Since: 2.18 - */ - - -/** - * g_emblem_new_with_origin: - * @icon: a GIcon containing the icon. - * @origin: a GEmblemOrigin enum defining the emblem's origin - * - * Creates a new emblem for @icon. - * - * Returns: a new #GEmblem. - * Since: 2.18 - */ - - -/** - * g_emblemed_icon_add_emblem: - * @emblemed: a #GEmblemedIcon - * @emblem: a #GEmblem - * - * Adds @emblem to the #GList of #GEmblems. - * - * Since: 2.18 - */ - - -/** - * g_emblemed_icon_clear_emblems: - * @emblemed: a #GEmblemedIcon - * - * Removes all the emblems from @icon. - * - * Since: 2.28 - */ - - -/** - * g_emblemed_icon_get_emblems: - * @emblemed: a #GEmblemedIcon - * - * Gets the list of emblems for the @icon. - * - * Returns: (element-type Gio.Emblem) (transfer none): a #GList of - * #GEmblems that is owned by @emblemed - * Since: 2.18 - */ - - -/** - * g_emblemed_icon_get_icon: - * @emblemed: a #GEmblemedIcon - * - * Gets the main icon for @emblemed. - * - * Returns: (transfer none): a #GIcon that is owned by @emblemed - * Since: 2.18 - */ - - -/** - * g_emblemed_icon_new: - * @icon: a #GIcon - * @emblem: (nullable): a #GEmblem, or %NULL - * - * Creates a new emblemed icon for @icon with the emblem @emblem. - * - * Returns: (transfer full) (type GEmblemedIcon): a new #GIcon - * Since: 2.18 - */ - - -/** - * g_file_append_to: - * @file: input #GFile - * @flags: a set of #GFileCreateFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Gets an output stream for appending data to the file. - * If the file doesn't already exist it is created. - * - * By default files created are generally readable by everyone, - * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file - * will be made readable only to the current user, to the level that - * is supported on the target filesystem. - * - * If @cancellable is not %NULL, then the operation can be cancelled - * by triggering the cancellable object from another thread. If the - * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be - * returned. - * - * Some file systems don't allow all file names, and may return an - * %G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the - * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are - * possible too, and depend on what kind of filesystem the file is on. - * - * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_append_to_async: - * @file: input #GFile - * @flags: a set of #GFileCreateFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously opens @file for appending. - * - * For more details, see g_file_append_to() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_append_to_finish() to get the result - * of the operation. - */ - - -/** - * g_file_append_to_finish: - * @file: input #GFile - * @res: #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous file append operation started with - * g_file_append_to_async(). - * - * Returns: (transfer full): a valid #GFileOutputStream - * or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_attribute_info_list_add: - * @list: a #GFileAttributeInfoList. - * @name: the name of the attribute to add. - * @type: the #GFileAttributeType for the attribute. - * @flags: #GFileAttributeInfoFlags for the attribute. - * - * Adds a new attribute with @name to the @list, setting - * its @type and @flags. - */ - - -/** - * g_file_attribute_info_list_dup: - * @list: a #GFileAttributeInfoList to duplicate. - * - * Makes a duplicate of a file attribute info list. - * - * Returns: a copy of the given @list. - */ - - -/** - * g_file_attribute_info_list_lookup: - * @list: a #GFileAttributeInfoList. - * @name: the name of the attribute to look up. - * - * Gets the file attribute with the name @name from @list. - * - * Returns: a #GFileAttributeInfo for the @name, or %NULL if an - * attribute isn't found. - */ - - -/** - * g_file_attribute_info_list_new: - * - * Creates a new file attribute info list. - * - * Returns: a #GFileAttributeInfoList. - */ - - -/** - * g_file_attribute_info_list_ref: - * @list: a #GFileAttributeInfoList to reference. - * - * References a file attribute info list. - * - * Returns: #GFileAttributeInfoList or %NULL on error. - */ - - -/** - * g_file_attribute_info_list_unref: - * @list: The #GFileAttributeInfoList to unreference. - * - * Removes a reference from the given @list. If the reference count - * falls to zero, the @list is deleted. - */ - - -/** - * g_file_attribute_matcher_enumerate_namespace: - * @matcher: a #GFileAttributeMatcher. - * @ns: a string containing a file attribute namespace. - * - * Checks if the matcher will match all of the keys in a given namespace. - * This will always return %TRUE if a wildcard character is in use (e.g. if - * matcher was created with "standard::*" and @ns is "standard", or if matcher was created - * using "*" and namespace is anything.) - * - * TODO: this is awkwardly worded. - * - * Returns: %TRUE if the matcher matches all of the entries - * in the given @ns, %FALSE otherwise. - */ - - -/** - * g_file_attribute_matcher_enumerate_next: - * @matcher: a #GFileAttributeMatcher. - * - * Gets the next matched attribute from a #GFileAttributeMatcher. - * - * Returns: (nullable): a string containing the next attribute or, %NULL if - * no more attribute exist. - */ - - -/** - * g_file_attribute_matcher_matches: - * @matcher: a #GFileAttributeMatcher. - * @attribute: a file attribute key. - * - * Checks if an attribute will be matched by an attribute matcher. If - * the matcher was created with the "*" matching string, this function - * will always return %TRUE. - * - * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise. - */ - - -/** - * g_file_attribute_matcher_matches_only: - * @matcher: a #GFileAttributeMatcher. - * @attribute: a file attribute key. - * - * Checks if a attribute matcher only matches a given attribute. Always - * returns %FALSE if "*" was used when creating the matcher. - * - * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise. - */ - - -/** - * g_file_attribute_matcher_new: - * @attributes: an attribute string to match. - * - * Creates a new file attribute matcher, which matches attributes - * against a given string. #GFileAttributeMatchers are reference - * counted structures, and are created with a reference count of 1. If - * the number of references falls to 0, the #GFileAttributeMatcher is - * automatically destroyed. - * - * The @attributes string should be formatted with specific keys separated - * from namespaces with a double colon. Several "namespace::key" strings may be - * concatenated with a single comma (e.g. "standard::type,standard::is-hidden"). - * The wildcard "*" may be used to match all keys and namespaces, or - * "namespace::*" will match all keys in a given namespace. - * - * ## Examples of file attribute matcher strings and results - * - * - `"*"`: matches all attributes. - * - `"standard::is-hidden"`: matches only the key is-hidden in the - * standard namespace. - * - `"standard::type,unix::*"`: matches the type key in the standard - * namespace and all keys in the unix namespace. - * - * Returns: a #GFileAttributeMatcher - */ - - -/** - * g_file_attribute_matcher_ref: - * @matcher: a #GFileAttributeMatcher. - * - * References a file attribute matcher. - * - * Returns: a #GFileAttributeMatcher. - */ - - -/** - * g_file_attribute_matcher_subtract: - * @matcher: (nullable): Matcher to subtract from - * @subtract: (nullable): The matcher to subtract - * - * Subtracts all attributes of @subtract from @matcher and returns - * a matcher that supports those attributes. - * - * Note that currently it is not possible to remove a single - * attribute when the @matcher matches the whole namespace - or remove - * a namespace or attribute when the matcher matches everything. This - * is a limitation of the current implementation, but may be fixed - * in the future. - * - * Returns: (nullable): A file attribute matcher matching all attributes of - * @matcher that are not matched by @subtract - */ - - -/** - * g_file_attribute_matcher_to_string: - * @matcher: (nullable): a #GFileAttributeMatcher. - * - * Prints what the matcher is matching against. The format will be - * equal to the format passed to g_file_attribute_matcher_new(). - * The output however, might not be identical, as the matcher may - * decide to use a different order or omit needless parts. - * - * Returns: a string describing the attributes the matcher matches - * against or %NULL if @matcher was %NULL. - * Since: 2.32 - */ - - -/** - * g_file_attribute_matcher_unref: - * @matcher: a #GFileAttributeMatcher. - * - * Unreferences @matcher. If the reference count falls below 1, - * the @matcher is automatically freed. - */ - - -/** - * g_file_attribute_value_dup: - * @other: a #GFileAttributeValue to duplicate. - * - * Duplicates a file attribute. - * - * Returns: a duplicate of the @other. - */ - - -/** - * g_file_attribute_value_set: - * @attr: a #GFileAttributeValue to set the value in. - * @new_value: a #GFileAttributeValue to get the value from. - * - * Sets an attribute's value from another attribute. - */ - - -/** - * g_file_build_attribute_list_for_copy: - * @file: a #GFile to copy attributes to - * @flags: a set of #GFileCopyFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, %NULL to ignore - * - * Prepares the file attribute query string for copying to @file. - * - * This function prepares an attribute query string to be - * passed to g_file_query_info() to get a list of attributes - * normally copied with the file (see g_file_copy_attributes() - * for the detailed description). This function is used by the - * implementation of g_file_copy_attributes() and is useful - * when one needs to query and set the attributes in two - * stages (e.g., for recursive move of a directory). - * - * Returns: an attribute query string for g_file_query_info(), - * or %NULL if an error occurs. - * Since: 2.68 - */ - - -/** - * g_file_copy: - * @source: input #GFile - * @destination: destination #GFile - * @flags: set of #GFileCopyFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @progress_callback: (nullable) (scope call): function to callback with - * progress information, or %NULL if progress information is not needed - * @progress_callback_data: (closure): user data to pass to @progress_callback - * @error: #GError to set on error, or %NULL - * - * Copies the file @source to the location specified by @destination. - * Can not handle recursive copies of directories. - * - * If the flag #G_FILE_COPY_OVERWRITE is specified an already - * existing @destination file is overwritten. - * - * If the flag #G_FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks - * will be copied as symlinks, otherwise the target of the - * @source symlink will be copied. - * - * If the flag #G_FILE_COPY_ALL_METADATA is specified then all the metadata - * that is possible to copy is copied, not just the default subset (which, - * for instance, does not include the owner, see #GFileInfo). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * If @progress_callback is not %NULL, then the operation can be monitored - * by setting this to a #GFileProgressCallback function. - * @progress_callback_data will be passed to this function. It is guaranteed - * that this callback will be called after all data has been transferred with - * the total number of bytes copied during the operation. - * - * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND error - * is returned, independent on the status of the @destination. - * - * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then - * the error %G_IO_ERROR_EXISTS is returned. - * - * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY - * error is returned. If trying to overwrite a directory with a directory the - * %G_IO_ERROR_WOULD_MERGE error is returned. - * - * If the source is a directory and the target does not exist, or - * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then the - * %G_IO_ERROR_WOULD_RECURSE error is returned. - * - * If you are interested in copying the #GFile object itself (not the on-disk - * file), see g_file_dup(). - * - * Returns: %TRUE on success, %FALSE otherwise. - */ - - -/** - * g_file_copy_async: - * @source: input #GFile - * @destination: destination #GFile - * @flags: set of #GFileCopyFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @progress_callback: (nullable) (scope notified): function to callback with progress - * information, or %NULL if progress information is not needed - * @progress_callback_data: (closure progress_callback) (nullable): user data to pass to @progress_callback - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied - * @user_data: (closure callback): the data to pass to callback function - * - * Copies the file @source to the location specified by @destination - * asynchronously. For details of the behaviour, see g_file_copy(). - * - * If @progress_callback is not %NULL, then that function that will be called - * just like in g_file_copy(). The callback will run in the default main context - * of the thread calling g_file_copy_async() — the same context as @callback is - * run in. - * - * When the operation is finished, @callback will be called. You can then call - * g_file_copy_finish() to get the result of the operation. - */ - - -/** - * g_file_copy_attributes: - * @source: a #GFile with attributes - * @destination: a #GFile to copy attributes to - * @flags: a set of #GFileCopyFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, %NULL to ignore - * - * Copies the file attributes from @source to @destination. - * - * Normally only a subset of the file attributes are copied, - * those that are copies in a normal file copy operation - * (which for instance does not include e.g. owner). However - * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then - * all the metadata that is possible to copy is copied. This - * is useful when implementing move by copy + delete source. - * - * Returns: %TRUE if the attributes were copied successfully, - * %FALSE otherwise. - */ - - -/** - * g_file_copy_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes copying the file started with g_file_copy_async(). - * - * Returns: a %TRUE on success, %FALSE on error. - */ - - -/** - * g_file_create: - * @file: input #GFile - * @flags: a set of #GFileCreateFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Creates a new file and returns an output stream for writing to it. - * The file must not already exist. - * - * By default files created are generally readable by everyone, - * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file - * will be made readable only to the current user, to the level - * that is supported on the target filesystem. - * - * If @cancellable is not %NULL, then the operation can be cancelled - * by triggering the cancellable object from another thread. If the - * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be - * returned. - * - * If a file or directory with this name already exists the - * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't - * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME - * error, and if the name is to long %G_IO_ERROR_FILENAME_TOO_LONG will - * be returned. Other errors are possible too, and depend on what kind - * of filesystem the file is on. - * - * Returns: (transfer full): a #GFileOutputStream for the newly created - * file, or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_create_async: - * @file: input #GFile - * @flags: a set of #GFileCreateFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously creates a new file and returns an output stream - * for writing to it. The file must not already exist. - * - * For more details, see g_file_create() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_create_finish() to get the result - * of the operation. - */ - - -/** - * g_file_create_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous file create operation started with - * g_file_create_async(). - * - * Returns: (transfer full): a #GFileOutputStream or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_create_readwrite: - * @file: a #GFile - * @flags: a set of #GFileCreateFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: return location for a #GError, or %NULL - * - * Creates a new file and returns a stream for reading and - * writing to it. The file must not already exist. - * - * By default files created are generally readable by everyone, - * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file - * will be made readable only to the current user, to the level - * that is supported on the target filesystem. - * - * If @cancellable is not %NULL, then the operation can be cancelled - * by triggering the cancellable object from another thread. If the - * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be - * returned. - * - * If a file or directory with this name already exists, the - * %G_IO_ERROR_EXISTS error will be returned. Some file systems don't - * allow all file names, and may return an %G_IO_ERROR_INVALID_FILENAME - * error, and if the name is too long, %G_IO_ERROR_FILENAME_TOO_LONG - * will be returned. Other errors are possible too, and depend on what - * kind of filesystem the file is on. - * - * Note that in many non-local file cases read and write streams are - * not supported, so make sure you really need to do read and write - * streaming, rather than just opening for reading or writing. - * - * Returns: (transfer full): a #GFileIOStream for the newly created - * file, or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_file_create_readwrite_async: - * @file: input #GFile - * @flags: a set of #GFileCreateFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously creates a new file and returns a stream - * for reading and writing to it. The file must not already exist. - * - * For more details, see g_file_create_readwrite() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_create_readwrite_finish() to get - * the result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_file_create_readwrite_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous file create operation started with - * g_file_create_readwrite_async(). - * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_file_delete: (virtual delete_file) - * @file: input #GFile - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Deletes a file. If the @file is a directory, it will only be - * deleted if it is empty. This has the same semantics as g_unlink(). - * - * If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows - * for deletion to be implemented avoiding - * [time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use): - * |[ - * g_autoptr(GError) local_error = NULL; - * if (!g_file_delete (my_file, my_cancellable, &local_error) && - * !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND)) - * { - * // deletion failed for some reason other than the file not existing: - * // so report the error - * g_warning ("Failed to delete %s: %s", - * g_file_peek_path (my_file), local_error->message); - * } - * ]| - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE if the file was deleted. %FALSE otherwise. - */ - - -/** - * g_file_delete_async: (virtual delete_file_async) - * @file: input #GFile - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 delete a file. If the @file is a directory, it will - * only be deleted if it is empty. This has the same semantics as - * g_unlink(). - * - * Since: 2.34 - */ - - -/** - * g_file_delete_finish: (virtual delete_file_finish) - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes deleting a file started with g_file_delete_async(). - * - * Returns: %TRUE if the file was deleted. %FALSE otherwise. - * Since: 2.34 - */ - - -/** - * g_file_descriptor_based_get_fd: - * @fd_based: a #GFileDescriptorBased. - * - * Gets the underlying file descriptor. - * - * Returns: The file descriptor - * Since: 2.24 - */ - - -/** - * g_file_dup: - * @file: input #GFile - * - * Duplicates a #GFile handle. This operation does not duplicate - * the actual file or directory represented by the #GFile; see - * g_file_copy() if attempting to copy a file. - * - * g_file_dup() is useful when a second handle is needed to the same underlying - * file, for use in a separate thread (#GFile is not thread-safe). For use - * within the same thread, use g_object_ref() to increment the existing object’s - * reference count. - * - * This call does no blocking I/O. - * - * Returns: (transfer full): a new #GFile that is a duplicate - * of the given #GFile. - */ - - -/** - * g_file_eject_mountable: - * @file: input #GFile - * @flags: flags affecting the operation - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: (closure): the data to pass to callback function - * - * Starts an asynchronous eject on a mountable. - * When this operation has completed, @callback will be called with - * @user_user data, and the operation can be finalized with - * g_file_eject_mountable_finish(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Deprecated: 2.22: Use g_file_eject_mountable_with_operation() instead. - */ - - -/** - * g_file_eject_mountable_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous eject operation started by - * g_file_eject_mountable(). - * - * Returns: %TRUE if the @file was ejected successfully. - * %FALSE otherwise. - * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() - * instead. - */ - - -/** - * g_file_eject_mountable_with_operation: - * @file: input #GFile - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation, - * or %NULL to avoid user interaction - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: (closure): the data to pass to callback function - * - * Starts an asynchronous eject on a mountable. - * When this operation has completed, @callback will be called with - * @user_user data, and the operation can be finalized with - * g_file_eject_mountable_with_operation_finish(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Since: 2.22 - */ - - -/** - * g_file_eject_mountable_with_operation_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous eject operation started by - * g_file_eject_mountable_with_operation(). - * - * Returns: %TRUE if the @file was ejected successfully. - * %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_file_enumerate_children: - * @file: input #GFile - * @attributes: an attribute query string - * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: #GError for error reporting - * - * Gets the requested information about the files in a directory. - * The result is a #GFileEnumerator object that will give out - * #GFileInfo objects for all the files in the directory. - * - * The @attributes value is a string that specifies the file - * attributes that should be gathered. It is not an error if - * it's not possible to read a particular requested attribute - * from a file - it just won't be set. @attributes should - * be a comma-separated list of attributes or attribute wildcards. - * The wildcard "*" means all attributes, and a wildcard like - * "standard::*" means all attributes in the standard namespace. - * An example attribute query be "standard::*,owner::user". - * The standard attributes are available as defines, like - * #G_FILE_ATTRIBUTE_STANDARD_NAME. - * - * If @cancellable is not %NULL, then the operation can be cancelled - * by triggering the cancellable object from another thread. If the - * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be - * returned. - * - * 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_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(). - */ - - -/** - * g_file_enumerate_children_async: - * @file: input #GFile - * @attributes: an attribute query string - * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously gets the requested information about the files - * in a directory. The result is a #GFileEnumerator object that will - * give out #GFileInfo objects for all the files in the directory. - * - * For more details, see g_file_enumerate_children() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. You can - * then call g_file_enumerate_children_finish() to get the result of - * the operation. - */ - - -/** - * g_file_enumerate_children_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError - * - * Finishes an async enumerate children operation. - * See g_file_enumerate_children_async(). - * - * Returns: (transfer full): a #GFileEnumerator or %NULL - * if an error occurred. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_enumerator_close: - * @enumerator: a #GFileEnumerator. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Releases all resources used by this enumerator, making the - * enumerator return %G_IO_ERROR_CLOSED on all calls. - * - * This will be automatically called when the last reference - * is dropped, but you might want to call this function to make - * sure resources are released as early as possible. - * - * Returns: #TRUE on success or #FALSE on error. - */ - - -/** - * g_file_enumerator_close_async: - * @enumerator: a #GFileEnumerator. - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously closes the file enumerator. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned in - * g_file_enumerator_close_finish(). - */ - - -/** - * g_file_enumerator_close_finish: - * @enumerator: a #GFileEnumerator. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes closing a file enumerator, started from g_file_enumerator_close_async(). - * - * If the file enumerator was already closed when g_file_enumerator_close_async() - * was called, then this function will report %G_IO_ERROR_CLOSED in @error, and - * return %FALSE. If the file enumerator had pending operation when the close - * operation was started, then this function will report %G_IO_ERROR_PENDING, and - * return %FALSE. If @cancellable was not %NULL, then the operation may have been - * cancelled by triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %FALSE will be - * returned. - * - * Returns: %TRUE if the close operation has finished successfully. - */ - - -/** - * 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 - * - * Get the #GFile container which is being enumerated. - * - * Returns: (transfer none): the #GFile which is being enumerated. - * Since: 2.18 - */ - - -/** - * g_file_enumerator_has_pending: - * @enumerator: a #GFileEnumerator. - * - * Checks if the file enumerator has pending operations. - * - * Returns: %TRUE if the @enumerator has pending operations. - */ - - -/** - * g_file_enumerator_is_closed: - * @enumerator: a #GFileEnumerator. - * - * Checks if the file enumerator has been closed. - * - * Returns: %TRUE if the @enumerator is closed. - */ - - -/** - * g_file_enumerator_iterate: - * @direnum: an open #GFileEnumerator - * @out_info: (out) (transfer none) (optional): Output location for the next #GFileInfo, or %NULL - * @out_child: (out) (transfer none) (optional): Output location for the next #GFile, or %NULL - * @cancellable: a #GCancellable - * @error: a #GError - * - * This is a version of g_file_enumerator_next_file() that's easier to - * use correctly from C programs. With g_file_enumerator_next_file(), - * the gboolean return value signifies "end of iteration or error", which - * requires allocation of a temporary #GError. - * - * In contrast, with this function, a %FALSE return from - * g_file_enumerator_iterate() *always* means - * "error". End of iteration is signaled by @out_info or @out_child being %NULL. - * - * Another crucial difference is that the references for @out_info and - * @out_child are owned by @direnum (they are cached as hidden - * properties). You must not unref them in your own code. This makes - * memory management significantly easier for C code in combination - * with loops. - * - * Finally, this function optionally allows retrieving a #GFile as - * well. - * - * You must specify at least one of @out_info or @out_child. - * - * The code pattern for correctly using g_file_enumerator_iterate() from C - * is: - * - * |[ - * direnum = g_file_enumerate_children (file, ...); - * while (TRUE) - * { - * GFileInfo *info; - * if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error)) - * goto out; - * if (!info) - * break; - * ... do stuff with "info"; do not unref it! ... - * } - * - * out: - * g_object_unref (direnum); // Note: frees the last @info - * ]| - * - * Since: 2.44 - */ - - -/** - * g_file_enumerator_next_file: - * @enumerator: a #GFileEnumerator. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Returns information for the next file in the enumerated object. - * Will block until the information is available. The #GFileInfo - * 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. - * - * Returns: (nullable) (transfer full): A #GFileInfo or %NULL on error - * or end of enumerator. Free the returned object with - * g_object_unref() when no longer needed. - */ - - -/** - * g_file_enumerator_next_files_async: - * @enumerator: a #GFileEnumerator. - * @num_files: the number of file info objects to request - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Request information for a number of files from the enumerator asynchronously. - * 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 - * error will be reported. If a request is cancelled the callback will be called - * with %G_IO_ERROR_CANCELLED. - * - * During an async request no other sync and async calls are allowed, and will - * result in %G_IO_ERROR_PENDING errors. - * - * Any outstanding i/o request with higher priority (lower numerical value) will - * be executed before an outstanding request with lower priority. Default - * priority is %G_PRIORITY_DEFAULT. - */ - - -/** - * g_file_enumerator_next_files_finish: - * @enumerator: a #GFileEnumerator. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). - * - * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfos. You must free the list with - * g_list_free() and unref the infos with g_object_unref() when you're - * done with them. - */ - - -/** - * g_file_enumerator_set_pending: - * @enumerator: a #GFileEnumerator. - * @pending: a boolean value. - * - * Sets the file enumerator as having pending operations. - */ - - -/** - * g_file_equal: - * @file1: the first #GFile - * @file2: the second #GFile - * - * Checks if the two given #GFiles refer to the same file. - * - * Note that two #GFiles that differ can still refer to the same - * file on the filesystem due to various forms of filename - * aliasing. - * - * This call does no blocking I/O. - * - * Returns: %TRUE if @file1 and @file2 are equal. - */ - - -/** - * g_file_find_enclosing_mount: - * @file: input #GFile - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError - * - * Gets a #GMount for the #GFile. - * - * #GMount is returned only for user interesting locations, see - * #GVolumeMonitor. If the #GFileIface for @file does not have a #mount, - * @error will be set to %G_IO_ERROR_NOT_FOUND and %NULL #will be returned. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: (transfer full): a #GMount where the @file is located - * or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_find_enclosing_mount_async: - * @file: a #GFile - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously gets the mount for the file. - * - * For more details, see g_file_find_enclosing_mount() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_find_enclosing_mount_finish() to - * get the result of the operation. - */ - - -/** - * g_file_find_enclosing_mount_finish: - * @file: a #GFile - * @res: a #GAsyncResult - * @error: a #GError - * - * Finishes an asynchronous find mount request. - * See g_file_find_enclosing_mount_async(). - * - * Returns: (transfer full): #GMount for given @file or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_get_basename: (virtual get_basename) - * @file: input #GFile - * - * Gets the base name (the last component of the path) for a given #GFile. - * - * If called for the top level of a system (such as the filesystem root - * or a uri like sftp://host/) it will return a single directory separator - * (and on Windows, possibly a drive letter). - * - * The base name is a byte string (not UTF-8). It has no defined encoding - * or rules other than it may not contain zero bytes. If you want to use - * filenames in a user interface you should use the display name that you - * can get by requesting the %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME - * attribute with g_file_query_info(). - * - * This call does no blocking I/O. - * - * Returns: (type filename) (nullable): string containing the #GFile's - * base name, or %NULL if given #GFile is invalid. The returned string - * should be freed with g_free() when no longer needed. - */ - - -/** - * g_file_get_child: - * @file: input #GFile - * @name: (type filename): string containing the child's basename - * - * Gets a child of @file with basename equal to @name. - * - * Note that the file with that specific name might not exist, but - * you can still have a #GFile that points to it. You can use this - * for instance to create that file. - * - * This call does no blocking I/O. - * - * Returns: (transfer full): a #GFile to a child specified by @name. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_get_child_for_display_name: - * @file: input #GFile - * @display_name: string to a possible child - * @error: return location for an error - * - * Gets the child of @file for a given @display_name (i.e. a UTF-8 - * version of the name). If this function fails, it returns %NULL - * and @error will be set. This is very useful when constructing a - * #GFile for a new file and the user entered the filename in the - * user interface, for instance when you select a directory and - * type a filename in the file selector. - * - * This call does no blocking I/O. - * - * Returns: (transfer full): a #GFile to the specified child, or - * %NULL if the display name couldn't be converted. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_get_parent: - * @file: input #GFile - * - * Gets the parent directory for the @file. - * If the @file represents the root directory of the - * file system, then %NULL will be returned. - * - * This call does no blocking I/O. - * - * Returns: (nullable) (transfer full): a #GFile structure to the - * parent of the given #GFile or %NULL if there is no parent. Free - * the returned object with g_object_unref(). - */ - - -/** - * g_file_get_parse_name: - * @file: input #GFile - * - * Gets the parse name of the @file. - * A parse name is a UTF-8 string that describes the - * file such that one can get the #GFile back using - * g_file_parse_name(). - * - * This is generally used to show the #GFile as a nice - * full-pathname kind of string in a user interface, - * like in a location entry. - * - * For local files with names that can safely be converted - * to UTF-8 the pathname is used, otherwise the IRI is used - * (a form of URI that allows UTF-8 characters unescaped). - * - * This call does no blocking I/O. - * - * Returns: a string containing the #GFile's parse name. - * The returned string should be freed with g_free() - * when no longer needed. - */ - - -/** - * g_file_get_path: (virtual get_path) - * @file: input #GFile - * - * Gets the local pathname for #GFile, if one exists. If non-%NULL, this is - * guaranteed to be an absolute, canonical path. It might contain symlinks. - * - * This call does no blocking I/O. - * - * Returns: (type filename) (nullable): string containing the #GFile's path, - * or %NULL if no such path exists. The returned string should be freed - * with g_free() when no longer needed. - */ - - -/** - * g_file_get_relative_path: (virtual get_relative_path) - * @parent: input #GFile - * @descendant: input #GFile - * - * Gets the path for @descendant relative to @parent. - * - * This call does no blocking I/O. - * - * Returns: (type filename) (nullable): string with the relative path from - * @descendant to @parent, or %NULL if @descendant doesn't have @parent as - * prefix. The returned string should be freed with g_free() when - * no longer needed. - */ - - -/** - * g_file_get_uri: - * @file: input #GFile - * - * Gets the URI for the @file. - * - * This call does no blocking I/O. - * - * Returns: a string containing the #GFile's URI. If the #GFile was constructed - * with an invalid URI, an invalid URI is returned. - * The returned string should be freed with g_free() - * when no longer needed. - */ - - -/** - * g_file_get_uri_scheme: - * @file: input #GFile - * - * Gets the URI scheme for a #GFile. - * RFC 3986 decodes the scheme as: - * |[ - * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * ]| - * Common schemes include "file", "http", "ftp", etc. - * - * The scheme can be different from the one used to construct the #GFile, - * in that it might be replaced with one that is logically equivalent to the #GFile. - * - * This call does no blocking I/O. - * - * Returns: (nullable): a string containing the URI scheme for the given - * #GFile or %NULL if the #GFile was constructed with an invalid URI. The - * returned string should be freed with g_free() when no longer needed. - */ - - -/** - * g_file_has_parent: - * @file: input #GFile - * @parent: (nullable): the parent to check for, or %NULL - * - * Checks if @file has a parent, and optionally, if it is @parent. - * - * If @parent is %NULL then this function returns %TRUE if @file has any - * parent at all. If @parent is non-%NULL then %TRUE is only returned - * if @file is an immediate child of @parent. - * - * Returns: %TRUE if @file is an immediate child of @parent (or any parent in - * the case that @parent is %NULL). - * Since: 2.24 - */ - - -/** - * g_file_has_prefix: (virtual prefix_matches) - * @file: input #GFile - * @prefix: input #GFile - * - * Checks whether @file has the prefix specified by @prefix. - * - * In other words, if the names of initial elements of @file's - * pathname match @prefix. Only full pathname elements are matched, - * so a path like /foo is not considered a prefix of /foobar, only - * of /foo/bar. - * - * A #GFile is not a prefix of itself. If you want to check for - * equality, use g_file_equal(). - * - * This call does no I/O, as it works purely on names. As such it can - * sometimes return %FALSE even if @file is inside a @prefix (from a - * filesystem point of view), because the prefix of @file is an alias - * of @prefix. - * - * Returns: %TRUE if the @file's parent, grandparent, etc is @prefix, - * %FALSE otherwise. - */ - - -/** - * g_file_has_uri_scheme: - * @file: input #GFile - * @uri_scheme: a string containing a URI scheme - * - * Checks to see if a #GFile has a given URI scheme. - * - * This call does no blocking I/O. - * - * Returns: %TRUE if #GFile's backend supports the - * given URI scheme, %FALSE if URI scheme is %NULL, - * not supported, or #GFile is invalid. - */ - - -/** - * g_file_hash: (virtual hash) - * @file: (type GFile): #gconstpointer to a #GFile - * - * Creates a hash value for a #GFile. - * - * This call does no blocking I/O. - * - * Returns: 0 if @file is not a valid #GFile, otherwise an - * integer that can be used as hash value for the #GFile. - * This function is intended for easily hashing a #GFile to - * add to a #GHashTable or similar data structure. - */ - - -/** - * g_file_icon_get_file: - * @icon: a #GIcon. - * - * Gets the #GFile associated with the given @icon. - * - * Returns: (transfer none): a #GFile. - */ - - -/** - * g_file_icon_new: - * @file: a #GFile. - * - * Creates a new icon for a file. - * - * Returns: (transfer full) (type GFileIcon): a #GIcon for the given - * @file, or %NULL on error. - */ - - -/** - * g_file_info_clear_status: - * @info: a #GFileInfo. - * - * Clears the status information from @info. - */ - - -/** - * g_file_info_copy_into: - * @src_info: source to copy attributes from. - * @dest_info: destination to copy attributes to. - * - * First clears all of the [GFileAttribute][gio-GFileAttribute] of @dest_info, - * and then copies all of the file attributes from @src_info to @dest_info. - */ - - -/** - * g_file_info_dup: - * @other: a #GFileInfo. - * - * Duplicates a file info structure. - * - * Returns: (transfer full): a duplicate #GFileInfo of @other. - */ - - -/** - * g_file_info_get_access_date_time: - * @info: a #GFileInfo. - * - * Gets the access time of the current @info and returns it as a - * #GDateTime. - * - * This requires the %G_FILE_ATTRIBUTE_TIME_ACCESS attribute. If - * %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC is provided, the resulting #GDateTime - * will have microsecond precision. - * - * Returns: (transfer full) (nullable): access time, or %NULL if unknown - * Since: 2.70 - */ - - -/** - * g_file_info_get_attribute_as_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets the value of a attribute, formatted as a string. - * This escapes things as needed to make the string valid - * UTF-8. - * - * Returns: (nullable): a UTF-8 string associated with the given @attribute, or - * %NULL if the attribute wasn’t set. - * When you're done with the string it must be freed with g_free(). - */ - - -/** - * g_file_info_get_attribute_boolean: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets the value of a boolean attribute. If the attribute does not - * contain a boolean value, %FALSE will be returned. - * - * Returns: the boolean value contained within the attribute. - */ - - -/** - * g_file_info_get_attribute_byte_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets the value of a byte string attribute. If the attribute does - * not contain a byte string, %NULL will be returned. - * - * Returns: (nullable): the contents of the @attribute value as a byte string, or - * %NULL otherwise. - */ - - -/** - * g_file_info_get_attribute_data: - * @info: a #GFileInfo - * @attribute: a file attribute key - * @type: (out) (optional): return location for the attribute type, or %NULL - * @value_pp: (out) (optional) (not nullable): return location for the - * attribute value, or %NULL; the attribute value will not be %NULL - * @status: (out) (optional): return location for the attribute status, or %NULL - * - * Gets the attribute type, value and status for an attribute key. - * - * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, - * %FALSE otherwise. - */ - - -/** - * g_file_info_get_attribute_int32: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets a signed 32-bit integer contained within the attribute. If the - * attribute does not contain a signed 32-bit integer, or is invalid, - * 0 will be returned. - * - * Returns: a signed 32-bit integer from the attribute. - */ - - -/** - * g_file_info_get_attribute_int64: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets a signed 64-bit integer contained within the attribute. If the - * attribute does not contain a signed 64-bit integer, or is invalid, - * 0 will be returned. - * - * Returns: a signed 64-bit integer from the attribute. - */ - - -/** - * g_file_info_get_attribute_object: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets the value of a #GObject attribute. If the attribute does - * not contain a #GObject, %NULL will be returned. - * - * Returns: (transfer none) (nullable): a #GObject associated with the given @attribute, - * or %NULL otherwise. - */ - - -/** - * g_file_info_get_attribute_status: - * @info: a #GFileInfo - * @attribute: a file attribute key - * - * Gets the attribute status for an attribute key. - * - * Returns: a #GFileAttributeStatus for the given @attribute, or - * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. - */ - - -/** - * g_file_info_get_attribute_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets the value of a string attribute. If the attribute does - * not contain a string, %NULL will be returned. - * - * Returns: (nullable): the contents of the @attribute value as a UTF-8 string, - * or %NULL otherwise. - */ - - -/** - * g_file_info_get_attribute_stringv: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets the value of a stringv attribute. If the attribute does - * not contain a stringv, %NULL will be returned. - * - * Returns: (transfer none) (nullable): the contents of the @attribute value as a stringv, - * or %NULL otherwise. Do not free. These returned strings are UTF-8. - * Since: 2.22 - */ - - -/** - * g_file_info_get_attribute_type: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets the attribute type for an attribute key. - * - * Returns: a #GFileAttributeType for the given @attribute, or - * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. - */ - - -/** - * g_file_info_get_attribute_uint32: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets an unsigned 32-bit integer contained within the attribute. If the - * attribute does not contain an unsigned 32-bit integer, or is invalid, - * 0 will be returned. - * - * Returns: an unsigned 32-bit integer from the attribute. - */ - - -/** - * g_file_info_get_attribute_uint64: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Gets a unsigned 64-bit integer contained within the attribute. If the - * attribute does not contain an unsigned 64-bit integer, or is invalid, - * 0 will be returned. - * - * Returns: a unsigned 64-bit integer from the attribute. - */ - - -/** - * g_file_info_get_content_type: - * @info: a #GFileInfo. - * - * Gets the file's content type. - * - * Returns: (nullable): a string containing the file's content type, - * or %NULL if unknown. - */ - - -/** - * g_file_info_get_creation_date_time: - * @info: a #GFileInfo. - * - * Gets the creation time of the current @info and returns it as a - * #GDateTime. - * - * This requires the %G_FILE_ATTRIBUTE_TIME_CREATED attribute. If - * %G_FILE_ATTRIBUTE_TIME_CREATED_USEC is provided, the resulting #GDateTime - * will have microsecond precision. - * - * Returns: (transfer full) (nullable): creation time, or %NULL if unknown - * Since: 2.70 - */ - - -/** - * 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: (nullable): a #GDateTime, or %NULL. - * Since: 2.36 - */ - - -/** - * g_file_info_get_display_name: - * @info: a #GFileInfo. - * - * Gets a display name for a file. This is guaranteed to always be set. - * - * Returns: (not nullable): a string containing the display name. - */ - - -/** - * g_file_info_get_edit_name: - * @info: a #GFileInfo. - * - * Gets the edit name for a file. - * - * Returns: a string containing the edit name. - */ - - -/** - * g_file_info_get_etag: - * @info: a #GFileInfo. - * - * Gets the [entity tag][gfile-etag] for a given - * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. - * - * Returns: (nullable): a string containing the value of the "etag:value" attribute. - */ - - -/** - * g_file_info_get_file_type: - * @info: a #GFileInfo. - * - * Gets a file's type (whether it is a regular file, symlink, etc). - * This is different from the file's content type, see g_file_info_get_content_type(). - * - * Returns: a #GFileType for the given file. - */ - - -/** - * g_file_info_get_icon: - * @info: a #GFileInfo. - * - * Gets the icon for a file. - * - * Returns: (nullable) (transfer none): #GIcon for the given @info. - */ - - -/** - * g_file_info_get_is_backup: - * @info: a #GFileInfo. - * - * Checks if a file is a backup file. - * - * Returns: %TRUE if file is a backup file, %FALSE otherwise. - */ - - -/** - * g_file_info_get_is_hidden: - * @info: a #GFileInfo. - * - * Checks if a file is hidden. - * - * Returns: %TRUE if the file is a hidden file, %FALSE otherwise. - */ - - -/** - * g_file_info_get_is_symlink: - * @info: a #GFileInfo. - * - * Checks if a file is a symlink. - * - * Returns: %TRUE if the given @info is a symlink. - */ - - -/** - * g_file_info_get_modification_date_time: - * @info: a #GFileInfo. - * - * Gets the modification time of the current @info and returns it as a - * #GDateTime. - * - * This requires the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute. If - * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is provided, the resulting #GDateTime - * will have microsecond precision. - * - * Returns: (transfer full) (nullable): modification time, or %NULL if unknown - * Since: 2.62 - */ - - -/** - * g_file_info_get_modification_time: - * @info: a #GFileInfo. - * @result: (out caller-allocates): a #GTimeVal. - * - * Gets the modification time of the current @info and sets it - * in @result. - * - * Deprecated: 2.62: Use g_file_info_get_modification_date_time() instead, as - * #GTimeVal is deprecated due to the year 2038 problem. - */ - - -/** - * g_file_info_get_name: - * @info: a #GFileInfo. - * - * Gets the name for a file. This is guaranteed to always be set. - * - * Returns: (type filename) (not nullable): a string containing the file name. - */ - - -/** - * g_file_info_get_size: - * @info: a #GFileInfo. - * - * Gets the file's size (in bytes). The size is retrieved through the value of - * the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute and is converted - * from #guint64 to #goffset before returning the result. - * - * Returns: a #goffset containing the file's size (in bytes). - */ - - -/** - * g_file_info_get_sort_order: - * @info: a #GFileInfo. - * - * Gets the value of the sort_order attribute from the #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. - * - * Returns: a #gint32 containing the value of the "standard::sort_order" attribute. - */ - - -/** - * g_file_info_get_symbolic_icon: - * @info: a #GFileInfo. - * - * Gets the symbolic icon for a file. - * - * Returns: (nullable) (transfer none): #GIcon for the given @info. - * Since: 2.34 - */ - - -/** - * g_file_info_get_symlink_target: - * @info: a #GFileInfo. - * - * Gets the symlink target for a given #GFileInfo. - * - * Returns: (nullable): a string containing the symlink target. - */ - - -/** - * g_file_info_has_attribute: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Checks if a file info structure has an attribute named @attribute. - * - * Returns: %TRUE if @info has an attribute named @attribute, - * %FALSE otherwise. - */ - - -/** - * g_file_info_has_namespace: - * @info: a #GFileInfo. - * @name_space: a file attribute namespace. - * - * Checks if a file info structure has an attribute in the - * specified @name_space. - * - * Returns: %TRUE if @info has an attribute in @name_space, - * %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_file_info_list_attributes: - * @info: a #GFileInfo. - * @name_space: (nullable): a file attribute key's namespace, or %NULL to list - * all attributes. - * - * Lists the file info structure's attributes. - * - * Returns: (nullable) (array zero-terminated=1) (transfer full): a - * null-terminated array of strings of all of the possible attribute - * types for the given @name_space, or %NULL on error. - */ - - -/** - * g_file_info_new: - * - * Creates a new file info structure. - * - * Returns: a #GFileInfo. - */ - - -/** - * g_file_info_remove_attribute: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * - * Removes all cases of @attribute from @info if it exists. - */ - - -/** - * g_file_info_set_access_date_time: - * @info: a #GFileInfo. - * @atime: (not nullable): a #GDateTime. - * - * Sets the %G_FILE_ATTRIBUTE_TIME_ACCESS and - * %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the - * given date/time value. - * - * Since: 2.70 - */ - - -/** - * g_file_info_set_attribute: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @type: a #GFileAttributeType - * @value_p: (not nullable): pointer to the value - * - * Sets the @attribute to contain the given value, if possible. To unset the - * attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type. - */ - - -/** - * g_file_info_set_attribute_boolean: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a boolean value. - * - * Sets the @attribute to contain the given @attr_value, - * if possible. - */ - - -/** - * g_file_info_set_attribute_byte_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a byte string. - * - * Sets the @attribute to contain the given @attr_value, - * if possible. - */ - - -/** - * g_file_info_set_attribute_int32: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a signed 32-bit integer - * - * Sets the @attribute to contain the given @attr_value, - * if possible. - */ - - -/** - * g_file_info_set_attribute_int64: - * @info: a #GFileInfo. - * @attribute: attribute name to set. - * @attr_value: int64 value to set attribute to. - * - * Sets the @attribute to contain the given @attr_value, - * if possible. - */ - - -/** - * g_file_info_set_attribute_mask: - * @info: a #GFileInfo. - * @mask: a #GFileAttributeMatcher. - * - * Sets @mask on @info to match specific attribute types. - */ - - -/** - * g_file_info_set_attribute_object: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a #GObject. - * - * Sets the @attribute to contain the given @attr_value, - * if possible. - */ - - -/** - * g_file_info_set_attribute_status: - * @info: a #GFileInfo - * @attribute: a file attribute key - * @status: a #GFileAttributeStatus - * - * Sets the attribute status for an attribute key. This is only - * needed by external code that implement g_file_set_attributes_from_info() - * or similar functions. - * - * The attribute must exist in @info for this to work. Otherwise %FALSE - * is returned and @info is unchanged. - * - * Returns: %TRUE if the status was changed, %FALSE if the key was not set. - * Since: 2.22 - */ - - -/** - * g_file_info_set_attribute_string: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: a UTF-8 string. - * - * Sets the @attribute to contain the given @attr_value, - * if possible. - */ - - -/** - * g_file_info_set_attribute_stringv: - * @info: a #GFileInfo. - * @attribute: a file attribute key - * @attr_value: (array zero-terminated=1) (element-type utf8): a %NULL - * terminated array of UTF-8 strings. - * - * Sets the @attribute to contain the given @attr_value, - * if possible. - * - * Sinze: 2.22 - */ - - -/** - * g_file_info_set_attribute_uint32: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: an unsigned 32-bit integer. - * - * Sets the @attribute to contain the given @attr_value, - * if possible. - */ - - -/** - * g_file_info_set_attribute_uint64: - * @info: a #GFileInfo. - * @attribute: a file attribute key. - * @attr_value: an unsigned 64-bit integer. - * - * Sets the @attribute to contain the given @attr_value, - * if possible. - */ - - -/** - * g_file_info_set_content_type: - * @info: a #GFileInfo. - * @content_type: a content type. See [GContentType][gio-GContentType] - * - * Sets the content type attribute for a given #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. - */ - - -/** - * g_file_info_set_creation_date_time: - * @info: a #GFileInfo. - * @creation_time: (not nullable): a #GDateTime. - * - * Sets the %G_FILE_ATTRIBUTE_TIME_CREATED and - * %G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the - * given date/time value. - * - * Since: 2.70 - */ - - -/** - * g_file_info_set_display_name: - * @info: a #GFileInfo. - * @display_name: a string containing a display name. - * - * Sets the display name for the current #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. - */ - - -/** - * g_file_info_set_edit_name: - * @info: a #GFileInfo. - * @edit_name: a string containing an edit name. - * - * Sets the edit name for the current file. - * See %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME. - */ - - -/** - * g_file_info_set_file_type: - * @info: a #GFileInfo. - * @type: a #GFileType. - * - * Sets the file type in a #GFileInfo to @type. - * See %G_FILE_ATTRIBUTE_STANDARD_TYPE. - */ - - -/** - * g_file_info_set_icon: - * @info: a #GFileInfo. - * @icon: a #GIcon. - * - * Sets the icon for a given #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_ICON. - */ - - -/** - * g_file_info_set_is_hidden: - * @info: a #GFileInfo. - * @is_hidden: a #gboolean. - * - * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden. - * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. - */ - - -/** - * g_file_info_set_is_symlink: - * @info: a #GFileInfo. - * @is_symlink: a #gboolean. - * - * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink. - * See %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK. - */ - - -/** - * g_file_info_set_modification_date_time: - * @info: a #GFileInfo. - * @mtime: (not nullable): a #GDateTime. - * - * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and - * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the - * given date/time value. - * - * Since: 2.62 - */ - - -/** - * g_file_info_set_modification_time: - * @info: a #GFileInfo. - * @mtime: a #GTimeVal. - * - * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED and - * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the - * given time value. - * - * Deprecated: 2.62: Use g_file_info_set_modification_date_time() instead, as - * #GTimeVal is deprecated due to the year 2038 problem. - */ - - -/** - * g_file_info_set_name: - * @info: a #GFileInfo. - * @name: (type filename): a string containing a name. - * - * Sets the name attribute for the current #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_NAME. - */ - - -/** - * g_file_info_set_size: - * @info: a #GFileInfo. - * @size: a #goffset containing the file's size. - * - * Sets the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info - * to the given size. - */ - - -/** - * g_file_info_set_sort_order: - * @info: a #GFileInfo. - * @sort_order: a sort order integer. - * - * Sets the sort order attribute in the file info structure. See - * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. - */ - - -/** - * g_file_info_set_symbolic_icon: - * @info: a #GFileInfo. - * @icon: a #GIcon. - * - * Sets the symbolic icon for a given #GFileInfo. - * See %G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON. - * - * Since: 2.34 - */ - - -/** - * g_file_info_set_symlink_target: - * @info: a #GFileInfo. - * @symlink_target: a static string containing a path to a symlink target. - * - * Sets the %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info - * to the given symlink target. - */ - - -/** - * g_file_info_unset_attribute_mask: - * @info: #GFileInfo. - * - * Unsets a mask set by g_file_info_set_attribute_mask(), if one - * is set. - */ - - -/** - * g_file_input_stream_query_info: - * @stream: a #GFileInputStream. - * @attributes: a file attribute query string. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Queries a file input stream the given @attributes. This function blocks - * while querying the stream. For the asynchronous (non-blocking) version - * of this function, see g_file_input_stream_query_info_async(). While the - * stream is blocked, the stream will set the pending flag internally, and - * any other operations on the stream will fail with %G_IO_ERROR_PENDING. - * - * Returns: (transfer full): a #GFileInfo, or %NULL on error. - */ - - -/** - * g_file_input_stream_query_info_async: - * @stream: a #GFileInputStream. - * @attributes: a file attribute query string. - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Queries the stream information asynchronously. - * When the operation is finished @callback will be called. - * You can then call g_file_input_stream_query_info_finish() - * to get the result of the operation. - * - * For the synchronous version of this function, - * see g_file_input_stream_query_info(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be set - */ - - -/** - * g_file_input_stream_query_info_finish: - * @stream: a #GFileInputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, - * or %NULL to ignore. - * - * Finishes an asynchronous info query operation. - * - * Returns: (transfer full): #GFileInfo. - */ - - -/** - * g_file_io_stream_get_etag: - * @stream: a #GFileIOStream. - * - * Gets the entity tag for the file when it has been written. - * This must be called after the stream has been written - * and closed, as the etag can change while writing. - * - * Returns: (nullable) (transfer full): the entity tag for the stream. - * Since: 2.22 - */ - - -/** - * g_file_io_stream_query_info: - * @stream: a #GFileIOStream. - * @attributes: a file attribute query string. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Queries a file io stream for the given @attributes. - * This function blocks while querying the stream. For the asynchronous - * version of this function, see g_file_io_stream_query_info_async(). - * While the stream is blocked, the stream will set the pending flag - * internally, and any other operations on the stream will fail with - * %G_IO_ERROR_PENDING. - * - * Can fail if the stream was already closed (with @error being set to - * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being - * set to %G_IO_ERROR_PENDING), or if querying info is not supported for - * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). I - * all cases of failure, %NULL will be returned. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will - * be returned. - * - * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error. - * Since: 2.22 - */ - - -/** - * g_file_io_stream_query_info_async: - * @stream: a #GFileIOStream. - * @attributes: a file attribute query string. - * @io_priority: the [I/O priority][gio-GIOScheduler] of the request - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Asynchronously queries the @stream for a #GFileInfo. When completed, - * @callback will be called with a #GAsyncResult which can be used to - * finish the operation with g_file_io_stream_query_info_finish(). - * - * For the synchronous version of this function, see - * g_file_io_stream_query_info(). - * - * Since: 2.22 - */ - - -/** - * g_file_io_stream_query_info_finish: - * @stream: a #GFileIOStream. - * @result: a #GAsyncResult. - * @error: a #GError, %NULL to ignore. - * - * Finalizes the asynchronous query started - * by g_file_io_stream_query_info_async(). - * - * Returns: (transfer full): A #GFileInfo for the finished query. - * Since: 2.22 - */ - - -/** - * g_file_is_native: - * @file: input #GFile - * - * Checks to see if a file is native to the platform. - * - * A native file is one expressed in the platform-native filename format, - * e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, - * as it might be on a locally mounted remote filesystem. - * - * On some systems non-native files may be available using the native - * filesystem via a userspace filesystem (FUSE), in these cases this call - * will return %FALSE, but g_file_get_path() will still return a native path. - * - * This call does no blocking I/O. - * - * Returns: %TRUE if @file is native - */ - - -/** - * g_file_load_bytes: - * @file: a #GFile - * @cancellable: (nullable): a #GCancellable or %NULL - * @etag_out: (out) (nullable) (optional): a location to place the current - * entity tag for the file, or %NULL if the entity tag is not needed - * @error: a location for a #GError or %NULL - * - * Loads the contents of @file and returns it as #GBytes. - * - * If @file is a resource:// based URI, the resulting bytes will reference the - * embedded resource instead of a copy. Otherwise, this is equivalent to calling - * g_file_load_contents() and g_bytes_new_take(). - * - * For resources, @etag_out will be set to %NULL. - * - * The data contained in the resulting #GBytes is always zero-terminated, but - * this is not included in the #GBytes length. The resulting #GBytes should be - * freed with g_bytes_unref() when no longer in use. - * - * Returns: (transfer full): a #GBytes or %NULL and @error is set - * Since: 2.56 - */ - - -/** - * g_file_load_bytes_async: - * @file: a #GFile - * @cancellable: (nullable): a #GCancellable or %NULL - * @callback: (scope async): a #GAsyncReadyCallback to call when the - * request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Asynchronously loads the contents of @file as #GBytes. - * - * If @file is a resource:// based URI, the resulting bytes will reference the - * embedded resource instead of a copy. Otherwise, this is equivalent to calling - * g_file_load_contents_async() and g_bytes_new_take(). - * - * @callback should call g_file_load_bytes_finish() to get the result of this - * asynchronous operation. - * - * See g_file_load_bytes() for more information. - * - * Since: 2.56 - */ - - -/** - * g_file_load_bytes_finish: - * @file: a #GFile - * @result: a #GAsyncResult provided to the callback - * @etag_out: (out) (nullable) (optional): a location to place the current - * entity tag for the file, or %NULL if the entity tag is not needed - * @error: a location for a #GError, or %NULL - * - * Completes an asynchronous request to g_file_load_bytes_async(). - * - * For resources, @etag_out will be set to %NULL. - * - * The data contained in the resulting #GBytes is always zero-terminated, but - * this is not included in the #GBytes length. The resulting #GBytes should be - * freed with g_bytes_unref() when no longer in use. - * - * See g_file_load_bytes() for more information. - * - * Returns: (transfer full): a #GBytes or %NULL and @error is set - * Since: 2.56 - */ - - -/** - * g_file_load_contents: - * @file: input #GFile - * @cancellable: optional #GCancellable object, %NULL to ignore - * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (optional): a location to place the length of the contents of the file, - * or %NULL if the length is not needed - * @etag_out: (out) (optional) (nullable): a location to place the current entity tag for the file, - * or %NULL if the entity tag is not needed - * @error: a #GError, or %NULL - * - * Loads the content of the file into memory. The data is always - * zero-terminated, but this is not included in the resultant @length. - * The returned @contents should be freed with g_free() when no longer - * needed. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE if the @file's contents were successfully loaded. - * %FALSE if there were errors. - */ - - -/** - * g_file_load_contents_async: - * @file: input #GFile - * @cancellable: 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 - * - * Starts an asynchronous load of the @file's contents. - * - * For more details, see g_file_load_contents() which is - * the synchronous version of this call. - * - * When the load operation has completed, @callback will be called - * with @user data. To finish the operation, call - * g_file_load_contents_finish() with the #GAsyncResult returned by - * the @callback. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - */ - - -/** - * g_file_load_contents_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (optional): a location to place the length of the contents of the file, - * or %NULL if the length is not needed - * @etag_out: (out) (optional) (nullable): a location to place the current entity tag for the file, - * or %NULL if the entity tag is not needed - * @error: a #GError, or %NULL - * - * Finishes an asynchronous load of the @file's contents. - * The contents are placed in @contents, and @length is set to the - * size of the @contents string. The @contents should be freed with - * g_free() when no longer needed. If @etag_out is present, it will be - * set to the new entity tag for the @file. - * - * Returns: %TRUE if the load was successful. If %FALSE and @error is - * present, it will be set appropriately. - */ - - -/** - * g_file_load_partial_contents_async: (skip) - * @file: input #GFile - * @cancellable: optional #GCancellable object, %NULL to ignore - * @read_more_callback: (scope call) (closure user_data): a - * #GFileReadMoreCallback to receive partial data - * and to specify whether further data should be read - * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback to call - * when the request is satisfied - * @user_data: the data to pass to the callback functions - * - * Reads the partial contents of a file. A #GFileReadMoreCallback should - * be used to stop reading from the file when appropriate, else this - * function will behave exactly as g_file_load_contents_async(). This - * operation can be finished by g_file_load_partial_contents_finish(). - * - * Users of this function should be aware that @user_data is passed to - * both the @read_more_callback and the @callback. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - */ - - -/** - * g_file_load_partial_contents_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (optional): a location to place the length of the contents of the file, - * or %NULL if the length is not needed - * @etag_out: (out) (optional) (nullable): a location to place the current entity tag for the file, - * or %NULL if the entity tag is not needed - * @error: a #GError, or %NULL - * - * Finishes an asynchronous partial load operation that was started - * with g_file_load_partial_contents_async(). The data is always - * zero-terminated, but this is not included in the resultant @length. - * The returned @contents should be freed with g_free() when no longer - * needed. - * - * Returns: %TRUE if the load was successful. If %FALSE and @error is - * present, it will be set appropriately. - */ - - -/** - * g_file_make_directory: - * @file: input #GFile - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Creates a directory. Note that this will only create a child directory - * of the immediate parent directory of the path or URI given by the #GFile. - * To recursively create directories, see g_file_make_directory_with_parents(). - * This function will fail if the parent directory does not exist, setting - * @error to %G_IO_ERROR_NOT_FOUND. If the file system doesn't support - * creating directories, this function will fail, setting @error to - * %G_IO_ERROR_NOT_SUPPORTED. - * - * For a local #GFile the newly created directory will have the default - * (current) ownership and permissions of the current process. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE on successful creation, %FALSE otherwise. - */ - - -/** - * g_file_make_directory_async: (virtual make_directory_async) - * @file: input #GFile - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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. - * - * Since: 2.38 - */ - - -/** - * g_file_make_directory_finish: (virtual 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(). - * - * Returns: %TRUE on successful directory creation, %FALSE otherwise. - * Since: 2.38 - */ - - -/** - * g_file_make_directory_with_parents: - * @file: input #GFile - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Creates a directory and any parent directories that may not - * exist similar to 'mkdir -p'. If the file system does not support - * creating directories, this function will fail, setting @error to - * %G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists, - * this function will fail setting @error to %G_IO_ERROR_EXISTS, unlike - * the similar g_mkdir_with_parents(). - * - * For a local #GFile the newly created directories will have the default - * (current) ownership and permissions of the current process. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE if all directories have been successfully created, %FALSE - * otherwise. - * Since: 2.18 - */ - - -/** - * g_file_make_symbolic_link: - * @file: a #GFile with the name of the symlink to create - * @symlink_value: (type filename): a string with the path for the target - * of the new symlink - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError - * - * Creates a symbolic link named @file which contains the string - * @symlink_value. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE on the creation of a new symlink, %FALSE otherwise. - */ - - -/** - * g_file_measure_disk_usage: - * @file: a #GFile - * @flags: #GFileMeasureFlags - * @cancellable: (nullable): optional #GCancellable - * @progress_callback: (nullable): a #GFileMeasureProgressCallback - * @progress_data: user_data for @progress_callback - * @disk_usage: (out) (optional): the number of bytes of disk space used - * @num_dirs: (out) (optional): the number of directories encountered - * @num_files: (out) (optional): the number of non-directories encountered - * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer - * - * Recursively measures the disk usage of @file. - * - * This is essentially an analog of the 'du' command, but it also - * reports the number of directories and non-directory files encountered - * (including things like symbolic links). - * - * By default, errors are only reported against the toplevel file - * itself. Errors found while recursing are silently ignored, unless - * %G_FILE_MEASURE_REPORT_ANY_ERROR is given in @flags. - * - * The returned size, @disk_usage, is in bytes and should be formatted - * with g_format_size() in order to get something reasonable for showing - * in a user interface. - * - * @progress_callback and @progress_data can be given to request - * periodic progress updates while scanning. See the documentation for - * #GFileMeasureProgressCallback for information about when and how the - * callback will be invoked. - * - * Returns: %TRUE if successful, with the out parameters set. - * %FALSE otherwise, with @error set. - * Since: 2.38 - */ - - -/** - * g_file_measure_disk_usage_async: - * @file: a #GFile - * @flags: #GFileMeasureFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable - * @progress_callback: (nullable): a #GFileMeasureProgressCallback - * @progress_data: user_data for @progress_callback - * @callback: (nullable): a #GAsyncReadyCallback to call when complete - * @user_data: the data to pass to callback function - * - * Recursively measures the disk usage of @file. - * - * This is the asynchronous version of g_file_measure_disk_usage(). See - * there for more information. - * - * Since: 2.38 - */ - - -/** - * g_file_measure_disk_usage_finish: - * @file: a #GFile - * @result: the #GAsyncResult passed to your #GAsyncReadyCallback - * @disk_usage: (out) (optional): the number of bytes of disk space used - * @num_dirs: (out) (optional): the number of directories encountered - * @num_files: (out) (optional): the number of non-directories encountered - * @error: (nullable): %NULL, or a pointer to a %NULL #GError pointer - * - * Collects the results from an earlier call to - * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for - * more information. - * - * Returns: %TRUE if successful, with the out parameters set. - * %FALSE otherwise, with @error set. - * Since: 2.38 - */ - - -/** - * g_file_monitor: - * @file: input #GFile - * @flags: a set of #GFileMonitorFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Obtains a file or directory monitor for the given file, - * depending on the type of the file. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: (transfer full): a #GFileMonitor for the given @file, - * or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.18 - */ - - -/** - * g_file_monitor_cancel: - * @monitor: a #GFileMonitor. - * - * Cancels a file monitor. - * - * Returns: always %TRUE - */ - - -/** - * g_file_monitor_directory: (virtual monitor_dir) - * @file: input #GFile - * @flags: a set of #GFileMonitorFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Obtains a directory monitor for the given file. - * This may fail if directory monitoring is not supported. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * 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(). - * - * Returns: (transfer full): a #GFileMonitor for the given @file, - * or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_monitor_emit_event: - * @monitor: a #GFileMonitor. - * @child: a #GFile. - * @other_file: a #GFile. - * @event_type: a set of #GFileMonitorEvent flags. - * - * Emits the #GFileMonitor::changed signal if a change - * has taken place. Should be called from file monitor - * implementations only. - * - * Implementations are responsible to call this method from the - * [thread-default main context][g-main-context-push-thread-default] of the - * thread that the monitor was created in. - */ - - -/** - * g_file_monitor_file: - * @file: input #GFile - * @flags: a set of #GFileMonitorFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Obtains a file monitor for the given file. If no file notification - * mechanism exists, then regular polling of the file is used. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * 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(). - */ - - -/** - * g_file_monitor_is_cancelled: - * @monitor: a #GFileMonitor - * - * Returns whether the monitor is canceled. - * - * Returns: %TRUE if monitor is canceled. %FALSE otherwise. - */ - - -/** - * g_file_monitor_set_rate_limit: - * @monitor: a #GFileMonitor. - * @limit_msecs: a non-negative integer with the limit in milliseconds - * to poll for changes - * - * Sets the rate limit to which the @monitor will report - * consecutive change events to the same file. - */ - - -/** - * g_file_mount_enclosing_volume: - * @location: input #GFile - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation - * or %NULL to avoid user interaction - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: the data to pass to callback function - * - * Starts a @mount_operation, mounting the volume that contains - * the file @location. - * - * When this operation has completed, @callback will be called with - * @user_user data, and the operation can be finalized with - * g_file_mount_enclosing_volume_finish(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - */ - - -/** - * g_file_mount_enclosing_volume_finish: - * @location: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes a mount operation started by g_file_mount_enclosing_volume(). - * - * Returns: %TRUE if successful. If an error has occurred, - * this function will return %FALSE and set @error - * appropriately if present. - */ - - -/** - * g_file_mount_mountable: - * @file: input #GFile - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation, - * or %NULL to avoid user interaction - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: (closure): the data to pass to callback function - * - * Mounts a file of type G_FILE_TYPE_MOUNTABLE. - * Using @mount_operation, you can request callbacks when, for instance, - * passwords are needed during authentication. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_mount_mountable_finish() to get - * the result of the operation. - */ - - -/** - * g_file_mount_mountable_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes a mount operation. See g_file_mount_mountable() for details. - * - * Finish an asynchronous mount operation that was started - * with g_file_mount_mountable(). - * - * Returns: (transfer full): a #GFile or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_move: - * @source: #GFile pointing to the source location - * @destination: #GFile pointing to the destination location - * @flags: set of #GFileCopyFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @progress_callback: (nullable) (scope call): #GFileProgressCallback - * function for updates - * @progress_callback_data: (closure): gpointer to user data for - * the callback function - * @error: #GError for returning error conditions, or %NULL - * - * Tries to move the file or directory @source to the location specified - * by @destination. If native move operations are supported then this is - * used, otherwise a copy + delete fallback is used. The native - * implementation may support moving directories (for instance on moves - * inside the same filesystem), but the fallback code does not. - * - * If the flag #G_FILE_COPY_OVERWRITE is specified an already - * existing @destination file is overwritten. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * If @progress_callback is not %NULL, then the operation can be monitored - * by setting this to a #GFileProgressCallback function. - * @progress_callback_data will be passed to this function. It is - * guaranteed that this callback will be called after all data has been - * transferred with the total number of bytes copied during the operation. - * - * If the @source file does not exist, then the %G_IO_ERROR_NOT_FOUND - * error is returned, independent on the status of the @destination. - * - * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, - * then the error %G_IO_ERROR_EXISTS is returned. - * - * If trying to overwrite a file over a directory, the %G_IO_ERROR_IS_DIRECTORY - * error is returned. If trying to overwrite a directory with a directory the - * %G_IO_ERROR_WOULD_MERGE error is returned. - * - * If the source is a directory and the target does not exist, or - * #G_FILE_COPY_OVERWRITE is specified and the target is a file, then - * the %G_IO_ERROR_WOULD_RECURSE error may be returned (if the native - * move operation isn't available). - * - * Returns: %TRUE on successful move, %FALSE otherwise. - */ - - -/** - * g_file_new_build_filename: - * @first_element: (type filename): the first element in the path - * @...: remaining elements in path, terminated by %NULL - * - * Constructs a #GFile from a series of elements using the correct - * separator for filenames. - * - * Using this function is equivalent to calling g_build_filename(), - * followed by g_file_new_for_path() on the result. - * - * Returns: (transfer full): a new #GFile - * Since: 2.56 - */ - - -/** - * g_file_new_for_commandline_arg: - * @arg: (type filename): a command line string - * - * Creates a #GFile with the given argument from the command line. - * The value of @arg can be either a URI, an absolute path or a - * relative path resolved relative to the current working directory. - * This operation never fails, but the returned object might not - * support any I/O operation if @arg points to a malformed path. - * - * Note that on Windows, this function expects its argument to be in - * UTF-8 -- not the system code page. This means that you - * should not use this function with string from argv as it is passed - * to main(). g_win32_get_command_line() will return a UTF-8 version of - * the commandline. #GApplication also uses UTF-8 but - * g_application_command_line_create_file_for_arg() may be more useful - * for you there. It is also always possible to use this function with - * #GOptionContext arguments of type %G_OPTION_ARG_FILENAME. - * - * Returns: (transfer full): a new #GFile. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_new_for_commandline_arg_and_cwd: - * @arg: (type filename): a command line string - * @cwd: (type filename): 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: (type filename): a string containing a relative or absolute path. - * The string must be encoded in the glib filename encoding. - * - * Constructs a #GFile for a given path. This operation never - * fails, but the returned object might not support any I/O - * operation if @path is malformed. - * - * Returns: (transfer full): a new #GFile for the given @path. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_new_for_uri: - * @uri: a UTF-8 string containing a URI - * - * Constructs a #GFile for a given URI. This operation never - * fails, but the returned object might not support any I/O - * operation if @uri is malformed or if the uri type is - * not supported. - * - * Returns: (transfer full): a new #GFile for the given @uri. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_new_tmp: - * @tmpl: (type filename) (nullable): Template for the file - * name, as in g_file_open_tmp(), or %NULL for a default template - * @iostream: (out): on return, a #GFileIOStream for the created file - * @error: a #GError, or %NULL - * - * Opens a file in the preferred directory for temporary files (as - * returned by g_get_tmp_dir()) and returns a #GFile and - * #GFileIOStream pointing to it. - * - * @tmpl should be a string in the GLib file name encoding - * containing a sequence of six 'X' characters, and containing no - * directory components. If it is %NULL, a default template is used. - * - * Unlike the other #GFile constructors, this will return %NULL if - * a temporary file could not be created. - * - * Returns: (transfer full): a new #GFile. - * Free the returned object with g_object_unref(). - * Since: 2.32 - */ - - -/** - * g_file_open_readwrite: - * @file: #GFile to open - * @cancellable: (nullable): a #GCancellable - * @error: a #GError, or %NULL - * - * Opens an existing file for reading and writing. The result is - * a #GFileIOStream that can be used to read and write the contents - * of the file. - * - * If @cancellable is not %NULL, then the operation can be cancelled - * by triggering the cancellable object from another thread. If the - * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be - * returned. - * - * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will - * be returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY - * error will be returned. Other errors are possible too, and depend on - * what kind of filesystem the file is on. Note that in many non-local - * file cases read and write streams are not supported, so make sure you - * really need to do read and write streaming, rather than just opening - * for reading or writing. - * - * Returns: (transfer full): #GFileIOStream or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_file_open_readwrite_async: - * @file: input #GFile - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously opens @file for reading and writing. - * - * For more details, see g_file_open_readwrite() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_open_readwrite_finish() to get - * the result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_file_open_readwrite_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous file read operation started with - * g_file_open_readwrite_async(). - * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_file_output_stream_get_etag: - * @stream: a #GFileOutputStream. - * - * Gets the entity tag for the file when it has been written. - * This must be called after the stream has been written - * and closed, as the etag can change while writing. - * - * Returns: (nullable) (transfer full): the entity tag for the stream. - */ - - -/** - * g_file_output_stream_query_info: - * @stream: a #GFileOutputStream. - * @attributes: a file attribute query string. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError, %NULL to ignore. - * - * Queries a file output stream for the given @attributes. - * This function blocks while querying the stream. For the asynchronous - * version of this function, see g_file_output_stream_query_info_async(). - * While the stream is blocked, the stream will set the pending flag - * internally, and any other operations on the stream will fail with - * %G_IO_ERROR_PENDING. - * - * Can fail if the stream was already closed (with @error being set to - * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being - * set to %G_IO_ERROR_PENDING), or if querying info is not supported for - * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In - * all cases of failure, %NULL will be returned. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL will - * be returned. - * - * Returns: (transfer full): a #GFileInfo for the @stream, or %NULL on error. - */ - - -/** - * g_file_output_stream_query_info_async: - * @stream: a #GFileOutputStream. - * @attributes: a file attribute query string. - * @io_priority: the [I/O priority][gio-GIOScheduler] of the request - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: callback to call when the request is satisfied - * @user_data: the data to pass to callback function - * - * Asynchronously queries the @stream for a #GFileInfo. When completed, - * @callback will be called with a #GAsyncResult which can be used to - * finish the operation with g_file_output_stream_query_info_finish(). - * - * For the synchronous version of this function, see - * g_file_output_stream_query_info(). - */ - - -/** - * g_file_output_stream_query_info_finish: - * @stream: a #GFileOutputStream. - * @result: a #GAsyncResult. - * @error: a #GError, %NULL to ignore. - * - * Finalizes the asynchronous query started - * by g_file_output_stream_query_info_async(). - * - * Returns: (transfer full): A #GFileInfo for the finished query. - */ - - -/** - * g_file_parse_name: - * @parse_name: a file name or path to be parsed - * - * Constructs a #GFile with the given @parse_name (i.e. something - * given by g_file_get_parse_name()). This operation never fails, - * but the returned object might not support any I/O operation if - * the @parse_name cannot be parsed. - * - * Returns: (transfer full): a new #GFile. - */ - - -/** - * g_file_peek_path: - * @file: input #GFile - * - * Exactly like g_file_get_path(), but caches the result via - * g_object_set_qdata_full(). This is useful for example in C - * applications which mix `g_file_*` APIs with native ones. It - * also avoids an extra duplicated string when possible, so will be - * generally more efficient. - * - * This call does no blocking I/O. - * - * Returns: (type filename) (nullable): string containing the #GFile's path, - * or %NULL if no such path exists. The returned string is owned by @file. - * Since: 2.56 - */ - - -/** - * g_file_poll_mountable: - * @file: input #GFile - * @cancellable: optional #GCancellable object, %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: the data to pass to callback function - * - * Polls a file of type #G_FILE_TYPE_MOUNTABLE. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_mount_mountable_finish() to get - * the result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_file_poll_mountable_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes a poll operation. See g_file_poll_mountable() for details. - * - * Finish an asynchronous poll operation that was polled - * with g_file_poll_mountable(). - * - * Returns: %TRUE if the operation finished successfully. %FALSE - * otherwise. - * Since: 2.22 - */ - - -/** - * g_file_query_default_handler: - * @file: a #GFile to open - * @cancellable: optional #GCancellable object, %NULL to ignore - * @error: a #GError, or %NULL - * - * Returns the #GAppInfo that is registered as the default - * application to handle the file specified by @file. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: (transfer full): a #GAppInfo if the handle was found, - * %NULL if there were errors. - * When you are done with it, release it with g_object_unref() - */ - - -/** - * g_file_query_default_handler_async: - * @file: a #GFile to open - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: optional #GCancellable object, %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done - * @user_data: (nullable): data to pass to @callback - * - * Async version of g_file_query_default_handler(). - * - * Since: 2.60 - */ - - -/** - * g_file_query_default_handler_finish: - * @file: a #GFile to open - * @result: a #GAsyncResult - * @error: (nullable): a #GError - * - * Finishes a g_file_query_default_handler_async() operation. - * - * Returns: (transfer full): a #GAppInfo if the handle was found, - * %NULL if there were errors. - * When you are done with it, release it with g_object_unref() - * Since: 2.60 - */ - - -/** - * g_file_query_exists: - * @file: input #GFile - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * - * Utility function to check if a particular file exists. This is - * implemented using g_file_query_info() and as such does blocking I/O. - * - * Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use) - * and then execute something based on the outcome of that, because the - * file might have been created or removed in between the operations. The - * general approach to handling that is to not check, but just do the - * operation and handle the errors as they come. - * - * As an example of race-free checking, take the case of reading a file, - * and if it doesn't exist, creating it. There are two racy versions: read - * it, and on error create it; and: check if it exists, if not create it. - * These can both result in two processes creating the file (with perhaps - * a partially written file as the result). The correct approach is to - * always try to create the file with g_file_create() which will either - * atomically create the file or fail with a %G_IO_ERROR_EXISTS error. - * - * However, in many cases an existence check is useful in a user interface, - * for instance to make a menu item sensitive/insensitive, so that you don't - * have to fool users that something is possible and then just show an error - * dialog. If you do this, you should make sure to also handle the errors - * that can happen due to races when you execute the operation. - * - * Returns: %TRUE if the file exists (and can be detected without error), - * %FALSE otherwise (or if cancelled). - */ - - -/** - * g_file_query_file_type: - * @file: input #GFile - * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info() - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * - * Utility function to inspect the #GFileType of a file. This is - * implemented using g_file_query_info() and as such does blocking I/O. - * - * The primary use case of this method is to check if a file is - * a regular file, directory, or symlink. - * - * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN - * if the file does not exist - * Since: 2.18 - */ - - -/** - * g_file_query_filesystem_info: - * @file: input #GFile - * @attributes: an attribute query string - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError - * - * Similar to g_file_query_info(), but obtains information - * about the filesystem the @file is on, rather than the file itself. - * For instance the amount of space available and the type of - * the filesystem. - * - * The @attributes value is a string that specifies the attributes - * that should be gathered. It is not an error if it's not possible - * to read a particular requested attribute from a file - it just - * won't be set. @attributes should be a comma-separated list of - * attributes or attribute wildcards. The wildcard "*" means all - * attributes, and a wildcard like "filesystem::*" means all attributes - * in the filesystem namespace. The standard namespace for filesystem - * attributes is "filesystem". Common attributes of interest are - * #G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem - * in bytes), #G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), - * and #G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem). - * - * If @cancellable is not %NULL, then the operation can be cancelled - * by triggering the cancellable object from another thread. If the - * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be - * returned. - * - * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will - * be returned. Other errors are possible too, and depend on what - * kind of filesystem the file is on. - * - * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_query_filesystem_info_async: - * @file: input #GFile - * @attributes: an attribute query string - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously gets the requested information about the filesystem - * that the specified @file is on. The result is a #GFileInfo object - * that contains key-value attributes (such as type or size for the - * file). - * - * For more details, see g_file_query_filesystem_info() which is the - * synchronous version of this call. - * - * When the operation is finished, @callback will be called. You can - * then call g_file_query_info_finish() to get the result of the - * operation. - */ - - -/** - * g_file_query_filesystem_info_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError - * - * Finishes an asynchronous filesystem info query. - * See g_file_query_filesystem_info_async(). - * - * Returns: (transfer full): #GFileInfo for given @file - * or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_query_info: - * @file: input #GFile - * @attributes: an attribute query string - * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError - * - * Gets the requested information about specified @file. - * The result is a #GFileInfo object that contains key-value - * attributes (such as the type or size of the file). - * - * The @attributes value is a string that specifies the file - * attributes that should be gathered. It is not an error if - * it's not possible to read a particular requested attribute - * from a file - it just won't be set. @attributes should be a - * comma-separated list of attributes or attribute wildcards. - * The wildcard "*" means all attributes, and a wildcard like - * "standard::*" means all attributes in the standard namespace. - * An example attribute query be "standard::*,owner::user". - * The standard attributes are available as defines, like - * #G_FILE_ATTRIBUTE_STANDARD_NAME. - * - * If @cancellable is not %NULL, then the operation can be cancelled - * by triggering the cancellable object from another thread. If the - * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be - * returned. - * - * For symlinks, normally the information about the target of the - * symlink is returned, rather than information about the symlink - * itself. However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS - * in @flags the information about the symlink itself will be returned. - * Also, for symlinks that point to non-existing files the information - * about the symlink itself will be returned. - * - * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be - * returned. Other errors are possible too, and depend on what kind of - * filesystem the file is on. - * - * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL - * on error. Free the returned object with g_object_unref(). - */ - - -/** - * g_file_query_info_async: - * @file: input #GFile - * @attributes: an attribute query string - * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously gets the requested information about specified @file. - * The result is a #GFileInfo object that contains key-value attributes - * (such as type or size for the file). - * - * For more details, see g_file_query_info() which is the synchronous - * version of this call. - * - * When the operation is finished, @callback will be called. You can - * then call g_file_query_info_finish() to get the result of the operation. - */ - - -/** - * g_file_query_info_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError - * - * Finishes an asynchronous file info query. - * See g_file_query_info_async(). - * - * Returns: (transfer full): #GFileInfo for given @file - * or %NULL on error. Free the returned object with - * g_object_unref(). - */ - - -/** - * g_file_query_settable_attributes: - * @file: input #GFile - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Obtain the list of settable attributes for the file. - * - * Returns the type and full attribute name of all the attributes - * that can be set on this file. This doesn't mean setting it will - * always succeed though, you might get an access failure, or some - * specific file may not support a specific attribute. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: a #GFileAttributeInfoList describing the settable attributes. - * When you are done with it, release it with - * g_file_attribute_info_list_unref() - */ - - -/** - * g_file_query_writable_namespaces: - * @file: input #GFile - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Obtain the list of attribute namespaces where new attributes - * can be created by a user. An example of this is extended - * attributes (in the "xattr" namespace). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: a #GFileAttributeInfoList describing the writable namespaces. - * When you are done with it, release it with - * g_file_attribute_info_list_unref() - */ - - -/** - * g_file_read: (virtual read_fn) - * @file: #GFile to read - * @cancellable: (nullable): a #GCancellable - * @error: a #GError, or %NULL - * - * Opens a file for reading. The result is a #GFileInputStream that - * can be used to read the contents of the file. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be - * returned. If the file is a directory, the %G_IO_ERROR_IS_DIRECTORY - * error will be returned. Other errors are possible too, and depend - * on what kind of filesystem the file is on. - * - * Returns: (transfer full): #GFileInputStream or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_read_async: - * @file: input #GFile - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously opens @file for reading. - * - * For more details, see g_file_read() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_read_finish() to get the result - * of the operation. - */ - - -/** - * g_file_read_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous file read operation started with - * g_file_read_async(). - * - * Returns: (transfer full): a #GFileInputStream or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_replace: - * @file: input #GFile - * @etag: (nullable): an optional [entity tag][gfile-etag] - * for the current #GFile, or #NULL to ignore - * @make_backup: %TRUE if a backup should be created - * @flags: a set of #GFileCreateFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Returns an output stream for overwriting the file, possibly - * creating a backup copy of the file first. If the file doesn't exist, - * it will be created. - * - * This will try to replace the file in the safest way possible so - * that any errors during the writing will not affect an already - * existing copy of the file. For instance, for local files it - * may write to a temporary file and then atomically rename over - * the destination when the stream is closed. - * - * By default files created are generally readable by everyone, - * but if you pass #G_FILE_CREATE_PRIVATE in @flags the file - * will be made readable only to the current user, to the level that - * is supported on the target filesystem. - * - * If @cancellable is not %NULL, then the operation can be cancelled - * by triggering the cancellable object from another thread. If the - * operation was cancelled, the error %G_IO_ERROR_CANCELLED will be - * returned. - * - * If you pass in a non-%NULL @etag value and @file already exists, then - * this value is compared to the current entity tag of the file, and if - * they differ an %G_IO_ERROR_WRONG_ETAG error is returned. This - * generally means that the file has been changed since you last read - * it. You can get the new etag from g_file_output_stream_get_etag() - * after you've finished writing and closed the #GFileOutputStream. When - * you load a new file you can use g_file_input_stream_query_info() to - * get the etag of the file. - * - * If @make_backup is %TRUE, this function will attempt to make a - * backup of the current file before overwriting it. If this fails - * a %G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you - * want to replace anyway, try again with @make_backup set to %FALSE. - * - * If the file is a directory the %G_IO_ERROR_IS_DIRECTORY error will - * be returned, and if the file is some other form of non-regular file - * then a %G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some - * file systems don't allow all file names, and may return an - * %G_IO_ERROR_INVALID_FILENAME error, and if the name is to long - * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are - * possible too, and depend on what kind of filesystem the file is on. - * - * Returns: (transfer full): a #GFileOutputStream or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_replace_async: - * @file: input #GFile - * @etag: (nullable): an [entity tag][gfile-etag] for the current #GFile, - * or %NULL to ignore - * @make_backup: %TRUE if a backup should be created - * @flags: a set of #GFileCreateFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously overwrites the file, replacing the contents, - * possibly creating a backup copy of the file first. - * - * For more details, see g_file_replace() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_replace_finish() to get the result - * of the operation. - */ - - -/** - * g_file_replace_contents: - * @file: input #GFile - * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file - * @length: the length of @contents in bytes - * @etag: (nullable): the old [entity-tag][gfile-etag] for the document, - * or %NULL - * @make_backup: %TRUE if a backup should be created - * @flags: a set of #GFileCreateFlags - * @new_etag: (out) (optional) (nullable): a location to a new [entity tag][gfile-etag] - * for the document. This should be freed with g_free() when no longer - * needed, or %NULL - * @cancellable: optional #GCancellable object, %NULL to ignore - * @error: a #GError, or %NULL - * - * Replaces the contents of @file with @contents of @length bytes. - * - * If @etag is specified (not %NULL), any existing file must have that etag, - * or the error %G_IO_ERROR_WRONG_ETAG will be returned. - * - * If @make_backup is %TRUE, this function will attempt to make a backup - * of @file. Internally, it uses g_file_replace(), so will try to replace the - * file contents in the safest way possible. For example, atomic renames are - * used when replacing local files’ contents. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * The returned @new_etag can be used to verify that the file hasn't - * changed the next time it is saved over. - * - * Returns: %TRUE if successful. If an error has occurred, this function - * will return %FALSE and set @error appropriately if present. - */ - - -/** - * g_file_replace_contents_async: - * @file: input #GFile - * @contents: (element-type guint8) (array length=length): string of contents to replace the file with - * @length: the length of @contents in bytes - * @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL - * @make_backup: %TRUE if a backup should be created - * @flags: a set of #GFileCreateFlags - * @cancellable: 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 - * - * Starts an asynchronous replacement of @file with the given - * @contents of @length bytes. @etag will replace the document's - * current entity tag. - * - * When this operation has completed, @callback will be called with - * @user_user data, and the operation can be finalized with - * g_file_replace_contents_finish(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * If @make_backup is %TRUE, this function will attempt to - * make a backup of @file. - * - * Note that no copy of @contents will be made, so it must stay valid - * until @callback is called. See g_file_replace_contents_bytes_async() - * for a #GBytes version that will automatically hold a reference to the - * contents (without copying) for the duration of the call. - */ - - -/** - * g_file_replace_contents_bytes_async: - * @file: input #GFile - * @contents: a #GBytes - * @etag: (nullable): a new [entity tag][gfile-etag] for the @file, or %NULL - * @make_backup: %TRUE if a backup should be created - * @flags: a set of #GFileCreateFlags - * @cancellable: 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 - * - * Same as g_file_replace_contents_async() but takes a #GBytes input instead. - * This function will keep a ref on @contents until the operation is done. - * Unlike g_file_replace_contents_async() this allows forgetting about the - * content without waiting for the callback. - * - * When this operation has completed, @callback will be called with - * @user_user data, and the operation can be finalized with - * g_file_replace_contents_finish(). - * - * Since: 2.40 - */ - - -/** - * g_file_replace_contents_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @new_etag: (out) (optional) (nullable): a location of a new [entity tag][gfile-etag] - * for the document. This should be freed with g_free() when it is no - * longer needed, or %NULL - * @error: a #GError, or %NULL - * - * Finishes an asynchronous replace of the given @file. See - * g_file_replace_contents_async(). Sets @new_etag to the new entity - * tag for the document, if present. - * - * Returns: %TRUE on success, %FALSE on failure. - */ - - -/** - * g_file_replace_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous file replace operation started with - * g_file_replace_async(). - * - * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_replace_readwrite: - * @file: a #GFile - * @etag: (nullable): an optional [entity tag][gfile-etag] - * for the current #GFile, or #NULL to ignore - * @make_backup: %TRUE if a backup should be created - * @flags: a set of #GFileCreateFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: return location for a #GError, or %NULL - * - * Returns an output stream for overwriting the file in readwrite mode, - * possibly creating a backup copy of the file first. If the file doesn't - * exist, it will be created. - * - * For details about the behaviour, see g_file_replace() which does the - * same thing but returns an output stream only. - * - * Note that in many non-local file cases read and write streams are not - * supported, so make sure you really need to do read and write streaming, - * rather than just opening for reading or writing. - * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_file_replace_readwrite_async: - * @file: input #GFile - * @etag: (nullable): an [entity tag][gfile-etag] for the current #GFile, - * or %NULL to ignore - * @make_backup: %TRUE if a backup should be created - * @flags: a set of #GFileCreateFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously overwrites the file in read-write mode, - * replacing the contents, possibly creating a backup copy - * of the file first. - * - * For more details, see g_file_replace_readwrite() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_replace_readwrite_finish() to get - * the result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_file_replace_readwrite_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an asynchronous file replace operation started with - * g_file_replace_readwrite_async(). - * - * Returns: (transfer full): a #GFileIOStream, or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_file_resolve_relative_path: - * @file: input #GFile - * @relative_path: (type filename): a given relative path string - * - * Resolves a relative path for @file to an absolute path. - * - * This call does no blocking I/O. - * - * Returns: (transfer full): #GFile to the resolved path. - * %NULL if @relative_path is %NULL or if @file is invalid. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_set_attribute: - * @file: input #GFile - * @attribute: a string containing the attribute's name - * @type: The type of the attribute - * @value_p: (nullable): a pointer to the value (or the pointer - * itself if the type is a pointer type) - * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Sets an attribute in the file with attribute name @attribute to @value_p. - * - * Some attributes can be unset by setting @type to - * %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE if the attribute was set, %FALSE otherwise. - */ - - -/** - * g_file_set_attribute_byte_string: - * @file: input #GFile - * @attribute: a string containing the attribute's name - * @value: a string containing the attribute's new value - * @flags: a #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. - * If @attribute is of a different type, this operation will fail, - * returning %FALSE. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE if the @attribute was successfully set to @value - * in the @file, %FALSE otherwise. - */ - - -/** - * g_file_set_attribute_int32: - * @file: input #GFile - * @attribute: a string containing the attribute's name - * @value: a #gint32 containing the attribute's new value - * @flags: a #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. - * If @attribute is of a different type, this operation will fail. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE if the @attribute was successfully set to @value - * in the @file, %FALSE otherwise. - */ - - -/** - * g_file_set_attribute_int64: - * @file: input #GFile - * @attribute: a string containing the attribute's name - * @value: a #guint64 containing the attribute's new value - * @flags: a #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. - * If @attribute is of a different type, this operation will fail. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise. - */ - - -/** - * g_file_set_attribute_string: - * @file: input #GFile - * @attribute: a string containing the attribute's name - * @value: a string containing the attribute's value - * @flags: #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. - * If @attribute is of a different type, this operation will fail. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE if the @attribute was successfully set, %FALSE otherwise. - */ - - -/** - * g_file_set_attribute_uint32: - * @file: input #GFile - * @attribute: a string containing the attribute's name - * @value: a #guint32 containing the attribute's new value - * @flags: a #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. - * If @attribute is of a different type, this operation will fail. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE if the @attribute was successfully set to @value - * in the @file, %FALSE otherwise. - */ - - -/** - * g_file_set_attribute_uint64: - * @file: input #GFile - * @attribute: a string containing the attribute's name - * @value: a #guint64 containing the attribute's new value - * @flags: a #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. - * If @attribute is of a different type, this operation will fail. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE if the @attribute was successfully set to @value - * in the @file, %FALSE otherwise. - */ - - -/** - * g_file_set_attributes_async: - * @file: input #GFile - * @info: a #GFileInfo - * @flags: a #GFileQueryInfoFlags - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): a #gpointer - * - * Asynchronously sets the attributes of @file with @info. - * - * For more details, see g_file_set_attributes_from_info(), - * which is the synchronous version of this call. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_set_attributes_finish() to get - * the result of the operation. - */ - - -/** - * g_file_set_attributes_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @info: (out) (transfer full): a #GFileInfo - * @error: a #GError, or %NULL - * - * Finishes setting an attribute started in g_file_set_attributes_async(). - * - * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise. - */ - - -/** - * g_file_set_attributes_from_info: - * @file: input #GFile - * @info: a #GFileInfo - * @flags: #GFileQueryInfoFlags - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Tries to set all attributes in the #GFileInfo on the target - * values, not stopping on the first error. - * - * If there is any error during this operation then @error will - * be set to the first error. Error on particular fields are flagged - * by setting the "status" field in the attribute value to - * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can - * also detect further errors. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %FALSE if there was any error, %TRUE otherwise. - */ - - -/** - * g_file_set_display_name: - * @file: input #GFile - * @display_name: a string - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Renames @file to the specified display name. - * - * The display name is converted from UTF-8 to the correct encoding - * for the target filesystem if possible and the @file is renamed to this. - * - * If you want to implement a rename operation in the user interface the - * edit name (#G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the - * initial value in the rename widget, and then the result after editing - * should be passed to g_file_set_display_name(). - * - * On success the resulting converted filename is returned. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: (transfer full): a #GFile specifying what @file was renamed to, - * or %NULL if there was an error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_set_display_name_async: - * @file: input #GFile - * @display_name: a string - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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 - * - * Asynchronously sets the display name for a given #GFile. - * - * For more details, see g_file_set_display_name() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_set_display_name_finish() to get - * the result of the operation. - */ - - -/** - * g_file_set_display_name_finish: - * @file: input #GFile - * @res: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes setting a display name started with - * g_file_set_display_name_async(). - * - * Returns: (transfer full): a #GFile or %NULL on error. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_file_start_mountable: - * @file: input #GFile - * @flags: flags affecting the operation - * @start_operation: (nullable): a #GMountOperation, or %NULL to avoid user interaction - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL - * @user_data: the data to pass to callback function - * - * Starts a file of type #G_FILE_TYPE_MOUNTABLE. - * Using @start_operation, you can request callbacks when, for instance, - * passwords are needed during authentication. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_mount_mountable_finish() to get - * the result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_file_start_mountable_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes a start operation. See g_file_start_mountable() for details. - * - * Finish an asynchronous start operation that was started - * with g_file_start_mountable(). - * - * Returns: %TRUE if the operation finished successfully. %FALSE - * otherwise. - * Since: 2.22 - */ - - -/** - * g_file_stop_mountable: - * @file: input #GFile - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation, - * or %NULL to avoid user interaction. - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: the data to pass to callback function - * - * Stops a file of type #G_FILE_TYPE_MOUNTABLE. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_stop_mountable_finish() to get - * the result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_file_stop_mountable_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes a stop operation, see g_file_stop_mountable() for details. - * - * Finish an asynchronous stop operation that was started - * with g_file_stop_mountable(). - * - * Returns: %TRUE if the operation finished successfully. - * %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_file_supports_thread_contexts: - * @file: a #GFile - * - * Checks if @file supports - * [thread-default contexts][g-main-context-push-thread-default-context]. - * If this returns %FALSE, you cannot perform asynchronous operations on - * @file in a thread that has a thread-default context. - * - * Returns: Whether or not @file supports thread-default contexts. - * Since: 2.22 - */ - - -/** - * g_file_trash: (virtual trash) - * @file: #GFile to send to trash - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @error: a #GError, or %NULL - * - * Sends @file to the "Trashcan", if possible. This is similar to - * deleting it, but the user can recover it before emptying the trashcan. - * Not all file systems support trashing, so this call can return the - * %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix - * mount option can be used to disable g_file_trash() support for certain - * mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE on successful trash, %FALSE otherwise. - */ - - -/** - * g_file_trash_async: (virtual trash_async) - * @file: input #GFile - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): 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. - * - * Since: 2.38 - */ - - -/** - * g_file_trash_finish: (virtual 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(). - * - * Returns: %TRUE on successful trash, %FALSE otherwise. - * Since: 2.38 - */ - - -/** - * g_file_unmount_mountable: - * @file: input #GFile - * @flags: flags affecting the operation - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: (closure): the data to pass to callback function - * - * Unmounts a file of type G_FILE_TYPE_MOUNTABLE. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_unmount_mountable_finish() to get - * the result of the operation. - * - * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation() instead. - */ - - -/** - * g_file_unmount_mountable_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an unmount operation, see g_file_unmount_mountable() for details. - * - * Finish an asynchronous unmount operation that was started - * with g_file_unmount_mountable(). - * - * Returns: %TRUE if the operation finished successfully. - * %FALSE otherwise. - * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() - * instead. - */ - - -/** - * g_file_unmount_mountable_with_operation: - * @file: input #GFile - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation, - * or %NULL to avoid user interaction - * @cancellable: (nullable): optional #GCancellable object, - * %NULL to ignore - * @callback: (scope async) (nullable): a #GAsyncReadyCallback to call - * when the request is satisfied, or %NULL - * @user_data: (closure): the data to pass to callback function - * - * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * When the operation is finished, @callback will be called. - * You can then call g_file_unmount_mountable_finish() to get - * the result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_file_unmount_mountable_with_operation_finish: - * @file: input #GFile - * @result: a #GAsyncResult - * @error: a #GError, or %NULL - * - * Finishes an unmount operation, - * see g_file_unmount_mountable_with_operation() for details. - * - * Finish an asynchronous unmount operation that was started - * with g_file_unmount_mountable_with_operation(). - * - * Returns: %TRUE if the operation finished successfully. - * %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_filename_completer_get_completion_suffix: - * @completer: the filename completer. - * @initial_text: text to be completed. - * - * Obtains a completion for @initial_text from @completer. - * - * Returns: (nullable) (transfer full): a completed string, or %NULL if no - * completion exists. This string is not owned by GIO, so remember to g_free() - * it when finished. - */ - - -/** - * g_filename_completer_get_completions: - * @completer: the filename completer. - * @initial_text: text to be completed. - * - * Gets an array of completion strings for a given initial text. - * - * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text. - * This array must be freed by g_strfreev() when finished. - */ - - -/** - * g_filename_completer_new: - * - * Creates a new filename completer. - * - * Returns: a #GFilenameCompleter. - */ - - -/** - * g_filename_completer_set_dirs_only: - * @completer: the filename completer. - * @dirs_only: a #gboolean. - * - * If @dirs_only is %TRUE, @completer will only - * complete directory names, and not file names. - */ - - -/** - * g_filter_input_stream_get_base_stream: - * @stream: a #GFilterInputStream. - * - * Gets the base stream for the filter stream. - * - * Returns: (transfer none): a #GInputStream. - */ - - -/** - * g_filter_input_stream_get_close_base_stream: - * @stream: a #GFilterInputStream. - * - * Returns whether the base stream will be closed when @stream is - * closed. - * - * Returns: %TRUE if the base stream will be closed. - */ - - -/** - * g_filter_input_stream_set_close_base_stream: - * @stream: a #GFilterInputStream. - * @close_base: %TRUE to close the base stream. - * - * Sets whether the base stream will be closed when @stream is closed. - */ - - -/** - * g_filter_output_stream_get_base_stream: - * @stream: a #GFilterOutputStream. - * - * Gets the base stream for the filter stream. - * - * Returns: (transfer none): a #GOutputStream. - */ - - -/** - * g_filter_output_stream_get_close_base_stream: - * @stream: a #GFilterOutputStream. - * - * Returns whether the base stream will be closed when @stream is - * closed. - * - * Returns: %TRUE if the base stream will be closed. - */ - - -/** - * g_filter_output_stream_set_close_base_stream: - * @stream: a #GFilterOutputStream. - * @close_base: %TRUE to close the base stream. - * - * Sets whether the base stream will be closed when @stream is closed. - */ - - -/** - * g_icon_deserialize: - * @value: (transfer none): a #GVariant created with g_icon_serialize() - * - * Deserializes a #GIcon previously serialized using g_icon_serialize(). - * - * Returns: (nullable) (transfer full): a #GIcon, or %NULL when deserialization fails. - * Since: 2.38 - */ - - -/** - * g_icon_equal: - * @icon1: (nullable): pointer to the first #GIcon. - * @icon2: (nullable): pointer to the second #GIcon. - * - * Checks if two icons are equal. - * - * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. - */ - - -/** - * g_icon_hash: (virtual hash) - * @icon: (not nullable): #gconstpointer to an icon object. - * - * Gets a hash for an icon. - * - * Returns: a #guint containing a hash for the @icon, suitable for - * use in a #GHashTable or similar data structure. - */ - - -/** - * g_icon_new_for_string: - * @str: A string obtained via g_icon_to_string(). - * @error: Return location for error. - * - * Generate a #GIcon instance from @str. This function can fail if - * @str is not valid - see g_icon_to_string() for discussion. - * - * 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(). - * - * Returns: (transfer full): An object implementing the #GIcon - * interface or %NULL if @error is set. - * Since: 2.20 - */ - - -/** - * 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: (nullable) (transfer full): a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. - * Since: 2.38 - */ - - -/** - * g_icon_to_string: (virtual to_tokens) - * @icon: a #GIcon. - * - * Generates a textual representation of @icon that can be used for - * serialization such as when passing @icon to a different process or - * saving it to persistent storage. Use g_icon_new_for_string() to - * get @icon back from the returned string. - * - * The encoding of the returned string is proprietary to #GIcon except - * in the following two cases - * - * - If @icon is a #GFileIcon, the returned string is a native path - * (such as `/path/to/my icon.png`) without escaping - * if the #GFile for @icon is a native file. If the file is not - * native, the returned string is the result of g_file_get_uri() - * (such as `sftp://path/to/my%20icon.png`). - * - * - If @icon is a #GThemedIcon with exactly one name and no fallbacks, - * the encoding is simply the name (such as `network-server`). - * - * Returns: (nullable): An allocated NUL-terminated UTF8 string or - * %NULL if @icon can't be serialized. Use g_free() to free. - * Since: 2.20 - */ - - -/** - * g_inet_address_equal: - * @address: A #GInetAddress. - * @other_address: Another #GInetAddress. - * - * Checks if two #GInetAddress instances are equal, e.g. the same address. - * - * Returns: %TRUE if @address and @other_address are equal, %FALSE otherwise. - * Since: 2.30 - */ - - -/** - * g_inet_address_get_family: - * @address: a #GInetAddress - * - * Gets @address's family - * - * Returns: @address's family - * Since: 2.22 - */ - - -/** - * g_inet_address_get_is_any: - * @address: a #GInetAddress - * - * Tests whether @address is the "any" address for its family. - * - * Returns: %TRUE if @address is the "any" address for its family. - * Since: 2.22 - */ - - -/** - * g_inet_address_get_is_link_local: - * @address: a #GInetAddress - * - * Tests whether @address is a link-local address (that is, if it - * identifies a host on a local network that is not connected to the - * Internet). - * - * Returns: %TRUE if @address is a link-local address. - * Since: 2.22 - */ - - -/** - * g_inet_address_get_is_loopback: - * @address: a #GInetAddress - * - * Tests whether @address is the loopback address for its family. - * - * Returns: %TRUE if @address is the loopback address for its family. - * Since: 2.22 - */ - - -/** - * g_inet_address_get_is_mc_global: - * @address: a #GInetAddress - * - * Tests whether @address is a global multicast address. - * - * Returns: %TRUE if @address is a global multicast address. - * Since: 2.22 - */ - - -/** - * g_inet_address_get_is_mc_link_local: - * @address: a #GInetAddress - * - * Tests whether @address is a link-local multicast address. - * - * Returns: %TRUE if @address is a link-local multicast address. - * Since: 2.22 - */ - - -/** - * g_inet_address_get_is_mc_node_local: - * @address: a #GInetAddress - * - * Tests whether @address is a node-local multicast address. - * - * Returns: %TRUE if @address is a node-local multicast address. - * Since: 2.22 - */ - - -/** - * g_inet_address_get_is_mc_org_local: - * @address: a #GInetAddress - * - * Tests whether @address is an organization-local multicast address. - * - * Returns: %TRUE if @address is an organization-local multicast address. - * Since: 2.22 - */ - - -/** - * g_inet_address_get_is_mc_site_local: - * @address: a #GInetAddress - * - * Tests whether @address is a site-local multicast address. - * - * Returns: %TRUE if @address is a site-local multicast address. - * Since: 2.22 - */ - - -/** - * g_inet_address_get_is_multicast: - * @address: a #GInetAddress - * - * Tests whether @address is a multicast address. - * - * Returns: %TRUE if @address is a multicast address. - * Since: 2.22 - */ - - -/** - * g_inet_address_get_is_site_local: - * @address: a #GInetAddress - * - * Tests whether @address is a site-local address such as 10.0.0.1 - * (that is, the address identifies a host on a local network that can - * not be reached directly from the Internet, but which may have - * outgoing Internet connectivity via a NAT or firewall). - * - * Returns: %TRUE if @address is a site-local address. - * Since: 2.22 - */ - - -/** - * g_inet_address_get_native_size: - * @address: a #GInetAddress - * - * Gets the size of the native raw binary address for @address. This - * is the size of the data that you get from g_inet_address_to_bytes(). - * - * Returns: the number of bytes used for the native version of @address. - * Since: 2.22 - */ - - -/** - * g_inet_address_mask_equal: - * @mask: a #GInetAddressMask - * @mask2: another #GInetAddressMask - * - * Tests if @mask and @mask2 are the same mask. - * - * Returns: whether @mask and @mask2 are the same mask - * Since: 2.32 - */ - - -/** - * g_inet_address_mask_get_address: - * @mask: a #GInetAddressMask - * - * Gets @mask's base address - * - * Returns: (transfer none): @mask's base address - * Since: 2.32 - */ - - -/** - * g_inet_address_mask_get_family: - * @mask: a #GInetAddressMask - * - * Gets the #GSocketFamily of @mask's address - * - * Returns: the #GSocketFamily of @mask's address - * Since: 2.32 - */ - - -/** - * g_inet_address_mask_get_length: - * @mask: a #GInetAddressMask - * - * Gets @mask's length - * - * Returns: @mask's length - * Since: 2.32 - */ - - -/** - * g_inet_address_mask_matches: - * @mask: a #GInetAddressMask - * @address: a #GInetAddress - * - * Tests if @address falls within the range described by @mask. - * - * Returns: whether @address falls within the range described by - * @mask. - * Since: 2.32 - */ - - -/** - * g_inet_address_mask_new: - * @addr: a #GInetAddress - * @length: number of bits of @addr to use - * @error: return location for #GError, or %NULL - * - * Creates a new #GInetAddressMask representing all addresses whose - * first @length bits match @addr. - * - * Returns: a new #GInetAddressMask, or %NULL on error - * Since: 2.32 - */ - - -/** - * g_inet_address_mask_new_from_string: - * @mask_string: an IP address or address/length string - * @error: return location for #GError, or %NULL - * - * Parses @mask_string as an IP address and (optional) length, and - * creates a new #GInetAddressMask. The length, if present, is - * delimited by a "/". If it is not present, then the length is - * assumed to be the full length of the address. - * - * Returns: a new #GInetAddressMask corresponding to @string, or %NULL - * on error. - * Since: 2.32 - */ - - -/** - * g_inet_address_mask_to_string: - * @mask: a #GInetAddressMask - * - * Converts @mask back to its corresponding string form. - * - * Returns: a string corresponding to @mask. - * Since: 2.32 - */ - - -/** - * g_inet_address_new_any: - * @family: the address family - * - * Creates a #GInetAddress for the "any" address (unassigned/"don't - * care") for @family. - * - * Returns: a new #GInetAddress corresponding to the "any" address - * for @family. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_inet_address_new_from_bytes: - * @bytes: (array) (element-type guint8): raw address data - * @family: the address family of @bytes - * - * Creates a new #GInetAddress from the given @family and @bytes. - * @bytes should be 4 bytes for %G_SOCKET_FAMILY_IPV4 and 16 bytes for - * %G_SOCKET_FAMILY_IPV6. - * - * Returns: a new #GInetAddress corresponding to @family and @bytes. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_inet_address_new_from_string: - * @string: a string representation of an IP address - * - * Parses @string as an IP address and creates a new #GInetAddress. - * - * Returns: (nullable) (transfer full): a new #GInetAddress corresponding - * to @string, or %NULL if @string could not be parsed. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_inet_address_new_loopback: - * @family: the address family - * - * Creates a #GInetAddress for the loopback address for @family. - * - * Returns: a new #GInetAddress corresponding to the loopback address - * for @family. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_inet_address_to_bytes: (skip) - * @address: a #GInetAddress - * - * Gets the raw binary address data from @address. - * - * Returns: a pointer to an internal array of the bytes in @address, - * which should not be modified, stored, or freed. The size of this - * array can be gotten with g_inet_address_get_native_size(). - * Since: 2.22 - */ - - -/** - * g_inet_address_to_string: - * @address: a #GInetAddress - * - * Converts @address to string form. - * - * Returns: a representation of @address as a string, which should be - * freed after use. - * Since: 2.22 - */ - - -/** - * g_inet_socket_address_get_address: - * @address: a #GInetSocketAddress - * - * Gets @address's #GInetAddress. - * - * Returns: (transfer none): the #GInetAddress for @address, which must be - * g_object_ref()'d if it will be stored - * Since: 2.22 - */ - - -/** - * g_inet_socket_address_get_flowinfo: - * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress - * - * Gets the `sin6_flowinfo` field from @address, - * which must be an IPv6 address. - * - * Returns: the flowinfo field - * Since: 2.32 - */ - - -/** - * g_inet_socket_address_get_port: - * @address: a #GInetSocketAddress - * - * Gets @address's port. - * - * Returns: the port for @address - * Since: 2.22 - */ - - -/** - * g_inet_socket_address_get_scope_id: - * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress - * - * Gets the `sin6_scope_id` field from @address, - * which must be an IPv6 address. - * - * Returns: the scope id field - * Since: 2.32 - */ - - -/** - * g_inet_socket_address_new: - * @address: a #GInetAddress - * @port: a port number - * - * Creates a new #GInetSocketAddress for @address and @port. - * - * Returns: a new #GInetSocketAddress - * Since: 2.22 - */ - - -/** - * g_inet_socket_address_new_from_string: - * @address: the string form of an IP address - * @port: a port number - * - * Creates a new #GInetSocketAddress for @address and @port. - * - * If @address is an IPv6 address, it can also contain a scope ID - * (separated from the address by a `%`). - * - * Returns: (nullable) (transfer full): a new #GInetSocketAddress, - * or %NULL if @address cannot be parsed. - * Since: 2.40 - */ - - -/** - * g_initable_init: - * @initable: a #GInitable. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Initializes the object implementing the interface. - * - * This method is intended for language bindings. If writing in C, - * g_initable_new() should typically be used instead. - * - * The object must be initialized before any real use after initial - * construction, either with this function or g_async_initable_init_async(). - * - * Implementations may also support cancellation. If @cancellable is not %NULL, - * then initialization can be cancelled by triggering the cancellable object - * from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be returned. If @cancellable is not %NULL and - * the object doesn't support cancellable initialization the error - * %G_IO_ERROR_NOT_SUPPORTED will be returned. - * - * If the object is not initialized, or initialization returns with an - * error, then all operations on the object except g_object_ref() and - * g_object_unref() are considered to be invalid, and have undefined - * behaviour. See the [introduction][ginitable] for more details. - * - * Callers should not assume that a class which implements #GInitable can be - * initialized multiple times, unless the class explicitly documents itself as - * supporting this. Generally, a class’ implementation of init() can assume - * (and assert) that it will only be called once. Previously, this documentation - * recommended all #GInitable implementations should be idempotent; that - * recommendation was relaxed in GLib 2.54. - * - * If a class explicitly supports being initialized multiple times, it is - * recommended that the method is idempotent: multiple calls with the same - * arguments should return the same results. Only the first call initializes - * the object; further calls return the result of the first call. - * - * One reason why a class might need to support idempotent initialization is if - * it is designed to be used via the singleton pattern, with a - * #GObjectClass.constructor that sometimes returns an existing instance. - * In this pattern, a caller would expect to be able to call g_initable_init() - * on the result of g_object_new(), regardless of whether it is in fact a new - * instance. - * - * Returns: %TRUE if successful. If an error has occurred, this function will - * return %FALSE and set @error appropriately if present. - * Since: 2.22 - */ - - -/** - * g_initable_new: - * @object_type: a #GType supporting #GInitable. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * @first_property_name: (nullable): the name of the first property, or %NULL if no - * properties - * @...: the value if the first property, followed by and other property - * value pairs, and ended by %NULL. - * - * Helper function for constructing #GInitable object. This is - * similar to g_object_new() but also initializes the object - * and returns %NULL, setting an error on failure. - * - * Returns: (type GObject.Object) (transfer full): a newly allocated - * #GObject, or %NULL on error - * Since: 2.22 - */ - - -/** - * g_initable_new_valist: - * @object_type: a #GType supporting #GInitable. - * @first_property_name: the name of the first property, followed by - * the value, and other property value pairs, and ended by %NULL. - * @var_args: The var args list generated from @first_property_name. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Helper function for constructing #GInitable object. This is - * similar to g_object_new_valist() but also initializes the object - * and returns %NULL, setting an error on failure. - * - * Returns: (type GObject.Object) (transfer full): a newly allocated - * #GObject, or %NULL on error - * Since: 2.22 - */ - - -/** - * g_initable_newv: - * @object_type: a #GType supporting #GInitable. - * @n_parameters: the number of parameters in @parameters - * @parameters: (array length=n_parameters): the parameters to use to construct the object - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Helper function for constructing #GInitable object. This is - * similar to g_object_newv() but also initializes the object - * and returns %NULL, setting an error on failure. - * - * Returns: (type GObject.Object) (transfer full): a newly allocated - * #GObject, or %NULL on error - * Since: 2.22 - * Deprecated: 2.54: Use g_object_new_with_properties() and - * g_initable_init() instead. See #GParameter for more information. - */ - - -/** - * g_input_stream_clear_pending: - * @stream: input stream - * - * Clears the pending flag on @stream. - */ - - -/** - * g_input_stream_close: - * @stream: A #GInputStream. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Closes the stream, releasing resources related to it. - * - * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. - * Closing a stream multiple times will not return an error. - * - * Streams will be automatically closed when the last reference - * is dropped, but you might want to call this function to make sure - * resources are released as early as possible. - * - * Some streams might keep the backing store of the stream (e.g. a file descriptor) - * open after the stream is closed. See the documentation for the individual - * stream for details. - * - * On failure the first error that happened will be reported, but the close - * operation will finish as much as possible. A stream that failed to - * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it - * is important to check and report the error to the user. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * Cancelling a close will still leave the stream closed, but some streams - * can use a faster close that doesn't block to e.g. check errors. - * - * Returns: %TRUE on success, %FALSE on failure - */ - - -/** - * g_input_stream_close_async: - * @stream: A #GInputStream. - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional cancellable object - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Requests an asynchronous closes of the stream, releasing resources related to it. - * When the operation is finished @callback will be called. - * You can then call g_input_stream_close_finish() to get the result of the - * operation. - * - * For behaviour details see g_input_stream_close(). - * - * The asynchronous methods have a default fallback that uses threads to implement - * asynchronicity, so they are optional for inheriting classes. However, if you - * override one you must override all. - */ - - -/** - * g_input_stream_close_finish: - * @stream: a #GInputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes closing a stream asynchronously, started from g_input_stream_close_async(). - * - * Returns: %TRUE if the stream was closed successfully. - */ - - -/** - * g_input_stream_has_pending: - * @stream: input stream. - * - * Checks if an input stream has pending actions. - * - * Returns: %TRUE if @stream has pending actions. - */ - - -/** - * g_input_stream_is_closed: - * @stream: input stream. - * - * Checks if an input stream is closed. - * - * Returns: %TRUE if the stream is closed. - */ - - -/** - * g_input_stream_read: - * @stream: a #GInputStream. - * @buffer: (array length=count) (element-type guint8) (out caller-allocates): - * a buffer to read data into (which should be at least count bytes long). - * @count: (in): the number of bytes that will be read from the stream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to read @count bytes from the stream into the buffer starting at - * @buffer. Will block during this read. - * - * If count is zero returns zero and does nothing. A value of @count - * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the number of bytes read into the buffer is returned. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. near the end of a file. Zero is returned on end of file - * (or if @count is zero), but never otherwise. - * - * The returned @buffer is not a nul-terminated string, it can contain nul bytes - * at any position, and this function doesn't nul-terminate the @buffer. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * - * On error -1 is returned and @error is set accordingly. - * - * Returns: Number of bytes read, or -1 on error, or 0 on end of file. - */ - - -/** - * g_input_stream_read_all: - * @stream: a #GInputStream. - * @buffer: (array length=count) (element-type guint8) (out caller-allocates): - * a buffer to read data into (which should be at least count bytes long). - * @count: (in): 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: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to read @count bytes from the stream into the buffer starting at - * @buffer. Will block during this read. - * - * This function is similar to g_input_stream_read(), except it tries to - * read as many bytes as requested, only stopping on an error or end of stream. - * - * On a successful read of @count bytes, or if we reached the end of the - * stream, %TRUE is returned, and @bytes_read is set to the number of bytes - * read into @buffer. - * - * If there is an error during the operation %FALSE is returned and @error - * is set to indicate the error status. - * - * As a special exception to the normal conventions for functions that - * use #GError, if this function returns %FALSE (and sets @error) then - * @bytes_read will be set to the number of bytes that were successfully - * read before the error was encountered. This functionality is only - * available from C. If you need it from another language then you must - * write your own loop around g_input_stream_read(). - * - * Returns: %TRUE on success, %FALSE if there was an error - */ - - -/** - * g_input_stream_read_all_async: - * @stream: A #GInputStream - * @buffer: (array length=count) (element-type guint8) (out caller-allocates): - * a buffer to read data into (which should be at least count bytes long) - * @count: (in): the number of bytes that will be read from the stream - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Request an asynchronous read of @count bytes from the stream into the - * buffer starting at @buffer. - * - * This is the asynchronous equivalent of g_input_stream_read_all(). - * - * Call g_input_stream_read_all_finish() to collect the result. - * - * Any outstanding I/O request with higher priority (lower numerical - * value) will be executed before an outstanding request with lower - * priority. Default priority is %G_PRIORITY_DEFAULT. - * - * Since: 2.44 - */ - - -/** - * g_input_stream_read_all_finish: - * @stream: a #GInputStream - * @result: a #GAsyncResult - * @bytes_read: (out): location to store the number of bytes that was read from the stream - * @error: a #GError location to store the error occurring, or %NULL to ignore - * - * Finishes an asynchronous stream read operation started with - * g_input_stream_read_all_async(). - * - * As a special exception to the normal conventions for functions that - * use #GError, if this function returns %FALSE (and sets @error) then - * @bytes_read will be set to the number of bytes that were successfully - * read before the error was encountered. This functionality is only - * available from C. If you need it from another language then you must - * write your own loop around g_input_stream_read_async(). - * - * Returns: %TRUE on success, %FALSE if there was an error - * Since: 2.44 - */ - - -/** - * g_input_stream_read_async: - * @stream: A #GInputStream. - * @buffer: (array length=count) (element-type guint8) (out caller-allocates): - * a buffer to read data into (which should be at least count bytes long). - * @count: (in): the number of bytes that will be read from the stream - * @io_priority: the [I/O priority][io-priority] - * of the request. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Request an asynchronous read of @count bytes from the stream into the buffer - * starting at @buffer. When the operation is finished @callback will be called. - * You can then call g_input_stream_read_finish() to get the result of the - * operation. - * - * During an async request no other sync and async calls are allowed on @stream, and will - * result in %G_IO_ERROR_PENDING errors. - * - * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the number of bytes read into the buffer will be passed to the - * callback. It is not an error if this is not the same as the requested size, as it - * can happen e.g. near the end of a file, but generally we try to read - * as many bytes as requested. Zero is returned on end of file - * (or if @count is zero), but never otherwise. - * - * Any outstanding i/o request with higher priority (lower numerical value) will - * be executed before an outstanding request with lower priority. Default - * priority is %G_PRIORITY_DEFAULT. - * - * The asynchronous methods have a default fallback that uses threads to implement - * asynchronicity, so they are optional for inheriting classes. However, if you - * override one you must override all. - */ - - -/** - * g_input_stream_read_bytes: - * @stream: a #GInputStream. - * @count: maximum number of bytes that will be read from the stream. Common - * values include 4096 and 8192. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Like g_input_stream_read(), this tries to read @count bytes from - * the stream in a blocking fashion. However, rather than reading into - * a user-supplied buffer, this will create a new #GBytes containing - * the data that was read. This may be easier to use from language - * bindings. - * - * If count is zero, returns a zero-length #GBytes and does nothing. A - * value of @count larger than %G_MAXSSIZE will cause a - * %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, a new #GBytes is returned. It is not an error if the - * size of this object is not the same as the requested size, as it - * can happen e.g. near the end of a file. A zero-length #GBytes is - * returned on end of file (or if @count is zero), but never - * otherwise. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * - * On error %NULL is returned and @error is set accordingly. - * - * Returns: (transfer full): a new #GBytes, or %NULL on error - * Since: 2.34 - */ - - -/** - * g_input_stream_read_bytes_async: - * @stream: A #GInputStream. - * @count: the number of bytes that will be read from the stream - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Request an asynchronous read of @count bytes from the stream into a - * new #GBytes. When the operation is finished @callback will be - * called. You can then call g_input_stream_read_bytes_finish() to get the - * result of the operation. - * - * During an async request no other sync and async calls are allowed - * on @stream, and will result in %G_IO_ERROR_PENDING errors. - * - * A value of @count larger than %G_MAXSSIZE will cause a - * %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the new #GBytes will be passed to the callback. It is - * not an error if this is smaller than the requested size, as it can - * happen e.g. near the end of a file, but generally we try to read as - * many bytes as requested. Zero is returned on end of file (or if - * @count is zero), but never otherwise. - * - * Any outstanding I/O request with higher priority (lower numerical - * value) will be executed before an outstanding request with lower - * priority. Default priority is %G_PRIORITY_DEFAULT. - * - * Since: 2.34 - */ - - -/** - * g_input_stream_read_bytes_finish: - * @stream: a #GInputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes an asynchronous stream read-into-#GBytes operation. - * - * Returns: (transfer full): the newly-allocated #GBytes, or %NULL on error - * Since: 2.34 - */ - - -/** - * g_input_stream_read_finish: - * @stream: a #GInputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes an asynchronous stream read operation. - * - * Returns: number of bytes read in, or -1 on error, or 0 on end of file. - */ - - -/** - * g_input_stream_set_pending: - * @stream: input stream - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Sets @stream to have actions pending. If the pending flag is - * already set or @stream is closed, it will return %FALSE and set - * @error. - * - * Returns: %TRUE if pending was previously unset and is now set. - */ - - -/** - * g_input_stream_skip: - * @stream: a #GInputStream. - * @count: the number of bytes that will be skipped from the stream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to skip @count bytes from the stream. Will block during the operation. - * - * This is identical to g_input_stream_read(), from a behaviour standpoint, - * but the bytes that are skipped are not returned to the user. Some - * streams have an implementation that is more efficient than reading the data. - * - * This function is optional for inherited classes, as the default implementation - * emulates it using read. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * - * Returns: Number of bytes skipped, or -1 on error - */ - - -/** - * g_input_stream_skip_async: - * @stream: A #GInputStream. - * @count: the number of bytes that will be skipped from the stream - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Request an asynchronous skip of @count bytes from the stream. - * When the operation is finished @callback will be called. - * You can then call g_input_stream_skip_finish() to get the result - * of the operation. - * - * During an async request no other sync and async calls are allowed, - * and will result in %G_IO_ERROR_PENDING errors. - * - * A value of @count larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the number of bytes skipped will be passed to the callback. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. near the end of a file, but generally we try to skip - * as many bytes as requested. Zero is returned on end of file - * (or if @count is zero), but never otherwise. - * - * Any outstanding i/o request with higher priority (lower numerical value) - * will be executed before an outstanding request with lower priority. - * Default priority is %G_PRIORITY_DEFAULT. - * - * The asynchronous methods have a default fallback that uses threads to - * implement asynchronicity, so they are optional for inheriting classes. - * However, if you override one, you must override all. - */ - - -/** - * g_input_stream_skip_finish: - * @stream: a #GInputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes a stream skip operation. - * - * Returns: the size of the bytes skipped, or `-1` on error. - */ - - -/** - * g_io_error_from_errno: - * @err_no: Error number as defined in errno.h. - * - * Converts errno.h error codes into GIO error codes. The fallback - * value %G_IO_ERROR_FAILED is returned for error codes not currently - * handled (but note that future GLib releases may return a more - * specific value instead). - * - * As %errno is global and may be modified by intermediate function - * calls, you should save its value as soon as the call which sets it - * - * Returns: #GIOErrorEnum value for the given errno.h error number. - */ - - -/** - * g_io_error_from_win32_error: - * @error_code: Windows error number. - * - * Converts some common error codes (as returned from GetLastError() - * or WSAGetLastError()) into GIO error codes. The fallback value - * %G_IO_ERROR_FAILED is returned for error codes not currently - * handled (but note that future GLib releases may return a more - * specific value instead). - * - * You can use g_win32_error_message() to get a localized string - * corresponding to @error_code. (But note that unlike g_strerror(), - * g_win32_error_message() returns a string that must be freed.) - * - * Returns: #GIOErrorEnum value for the given error number. - * Since: 2.26 - */ - - -/** - * g_io_error_quark: - * - * Gets the GIO Error Quark. - * - * Returns: a #GQuark. - */ - - -/** - * g_io_extension_get_name: - * @extension: a #GIOExtension - * - * Gets the name under which @extension was registered. - * - * Note that the same type may be registered as extension - * for multiple extension points, under different names. - * - * Returns: the name of @extension. - */ - - -/** - * g_io_extension_get_priority: - * @extension: a #GIOExtension - * - * Gets the priority with which @extension was registered. - * - * Returns: the priority of @extension - */ - - -/** - * g_io_extension_get_type: - * @extension: a #GIOExtension - * - * Gets the type associated with @extension. - * - * Returns: the type of @extension - */ - - -/** - * g_io_extension_point_get_extension_by_name: - * @extension_point: a #GIOExtensionPoint - * @name: the name of the extension to get - * - * Finds a #GIOExtension for an extension point by name. - * - * Returns: (transfer none): the #GIOExtension for @extension_point that has the - * given name, or %NULL if there is no extension with that name - */ - - -/** - * g_io_extension_point_get_extensions: - * @extension_point: a #GIOExtensionPoint - * - * Gets a list of all extensions that implement this extension point. - * The list is sorted by priority, beginning with the highest priority. - * - * Returns: (element-type GIOExtension) (transfer none): a #GList of - * #GIOExtensions. The list is owned by GIO and should not be - * modified. - */ - - -/** - * g_io_extension_point_get_required_type: - * @extension_point: a #GIOExtensionPoint - * - * Gets the required type for @extension_point. - * - * Returns: the #GType that all implementations must have, - * or #G_TYPE_INVALID if the extension point has no required type - */ - - -/** - * g_io_extension_point_implement: - * @extension_point_name: the name of the extension point - * @type: the #GType to register as extension - * @extension_name: the name for the extension - * @priority: the priority for the extension - * - * Registers @type as extension for the extension point with name - * @extension_point_name. - * - * If @type has already been registered as an extension for this - * extension point, the existing #GIOExtension object is returned. - * - * Returns: (transfer none): a #GIOExtension object for #GType - */ - - -/** - * g_io_extension_point_lookup: - * @name: the name of the extension point - * - * Looks up an existing extension point. - * - * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there - * is no registered extension point with the given name. - */ - - -/** - * g_io_extension_point_register: - * @name: The name of the extension point - * - * Registers an extension point. - * - * Returns: (transfer none): the new #GIOExtensionPoint. This object is - * owned by GIO and should not be freed. - */ - - -/** - * g_io_extension_point_set_required_type: - * @extension_point: a #GIOExtensionPoint - * @type: the #GType to require - * - * Sets the required type for @extension_point to @type. - * All implementations must henceforth have this type. - */ - - -/** - * g_io_extension_ref_class: - * @extension: a #GIOExtension - * - * Gets a reference to the class for the type that is - * associated with @extension. - * - * Returns: (transfer full): the #GTypeClass for the type of @extension - */ - - -/** - * g_io_module_new: - * @filename: (type filename): filename of the shared library module. - * - * Creates a new GIOModule that will load the specific - * shared library when in use. - * - * Returns: a #GIOModule from given @filename, - * or %NULL on error. - */ - - -/** - * g_io_module_scope_block: - * @scope: a module loading scope - * @basename: the basename to block - * - * Block modules with the given @basename from being loaded when - * this scope is used with g_io_modules_scan_all_in_directory_with_scope() - * or g_io_modules_load_all_in_directory_with_scope(). - * - * Since: 2.30 - */ - - -/** - * g_io_module_scope_free: - * @scope: a module loading scope - * - * Free a module scope. - * - * Since: 2.30 - */ - - -/** - * g_io_module_scope_new: - * @flags: flags for the new scope - * - * Create a new scope for loading of IO modules. A scope can be used for - * blocking duplicate modules, or blocking a module you don't want to load. - * - * Specify the %G_IO_MODULE_SCOPE_BLOCK_DUPLICATES flag to block modules - * which have the same base name as a module that has already been seen - * in this scope. - * - * Returns: (transfer full): the new module scope - * Since: 2.30 - */ - - -/** - * g_io_modules_load_all_in_directory: - * @dirname: (type filename): pathname for a directory containing modules - * to load. - * - * Loads all the modules in the specified directory. - * - * If don't require all modules to be initialized (and thus registering - * all gtypes) then you can use g_io_modules_scan_all_in_directory() - * which allows delayed/lazy loading of modules. - * - * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded - * from the directory, - * All the modules are loaded into memory, if you want to - * unload them (enabling on-demand loading) you must call - * g_type_module_unuse() on all the modules. Free the list - * with g_list_free(). - */ - - -/** - * g_io_modules_load_all_in_directory_with_scope: - * @dirname: (type filename): pathname for a directory containing modules - * to load. - * @scope: a scope to use when scanning the modules. - * - * Loads all the modules in the specified directory. - * - * If don't require all modules to be initialized (and thus registering - * all gtypes) then you can use g_io_modules_scan_all_in_directory() - * which allows delayed/lazy loading of modules. - * - * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded - * from the directory, - * All the modules are loaded into memory, if you want to - * unload them (enabling on-demand loading) you must call - * g_type_module_unuse() on all the modules. Free the list - * with g_list_free(). - * Since: 2.30 - */ - - -/** - * g_io_modules_scan_all_in_directory: - * @dirname: (type filename): pathname for a directory containing modules - * to scan. - * - * Scans all the modules in the specified directory, ensuring that - * any extension point implemented by a module is registered. - * - * This may not actually load and initialize all the types in each - * module, some modules may be lazily loaded and initialized when - * an extension point it implements is used with e.g. - * g_io_extension_point_get_extensions() or - * g_io_extension_point_get_extension_by_name(). - * - * If you need to guarantee that all types are loaded in all the modules, - * use g_io_modules_load_all_in_directory(). - * - * Since: 2.24 - */ - - -/** - * g_io_modules_scan_all_in_directory_with_scope: - * @dirname: (type filename): pathname for a directory containing modules - * to scan. - * @scope: a scope to use when scanning the modules - * - * Scans all the modules in the specified directory, ensuring that - * any extension point implemented by a module is registered. - * - * This may not actually load and initialize all the types in each - * module, some modules may be lazily loaded and initialized when - * an extension point it implements is used with e.g. - * g_io_extension_point_get_extensions() or - * g_io_extension_point_get_extension_by_name(). - * - * If you need to guarantee that all types are loaded in all the modules, - * use g_io_modules_load_all_in_directory(). - * - * Since: 2.30 - */ - - -/** - * g_io_scheduler_cancel_all_jobs: - * - * Cancels all cancellable I/O jobs. - * - * 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. - */ - - -/** - * g_io_scheduler_job_send_to_mainloop: - * @job: a #GIOSchedulerJob - * @func: a #GSourceFunc callback that will be called in the original thread - * @user_data: data to pass to @func - * @notify: (nullable): a #GDestroyNotify for @user_data, or %NULL - * - * Used from an I/O job to send a callback to be run in the thread - * that the job was started from, waiting for the result (and thus - * blocking the I/O job). - * - * Returns: The return value of @func - * Deprecated: Use g_main_context_invoke(). - */ - - -/** - * g_io_scheduler_job_send_to_mainloop_async: - * @job: a #GIOSchedulerJob - * @func: a #GSourceFunc callback that will be called in the original thread - * @user_data: data to pass to @func - * @notify: (nullable): a #GDestroyNotify for @user_data, or %NULL - * - * Used from an I/O job to send a callback to be run asynchronously in - * the thread that the job was started from. The callback will be run - * when the main loop is available, but at that time the I/O job might - * have finished. The return value from the callback is ignored. - * - * Note that if you are passing the @user_data from g_io_scheduler_push_job() - * 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(). - */ - - -/** - * g_io_scheduler_push_job: - * @job_func: a #GIOSchedulerJobFunc. - * @user_data: data to pass to @job_func - * @notify: (nullable): a #GDestroyNotify for @user_data, or %NULL - * @io_priority: the [I/O priority][io-priority] - * of the request. - * @cancellable: optional #GCancellable object, %NULL to ignore. - * - * Schedules the I/O job to run in another thread. - * - * @notify will be called on @user_data after @job_func has returned, - * regardless whether the job was cancelled or has run to completion. - * - * 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() - */ - - -/** - * g_io_stream_clear_pending: - * @stream: a #GIOStream - * - * Clears the pending flag on @stream. - * - * Since: 2.22 - */ - - -/** - * g_io_stream_close: - * @stream: a #GIOStream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @error: location to store the error occurring, or %NULL to ignore - * - * Closes the stream, releasing resources related to it. This will also - * close the individual input and output streams, if they are not already - * closed. - * - * Once the stream is closed, all other operations will return - * %G_IO_ERROR_CLOSED. Closing a stream multiple times will not - * return an error. - * - * Closing a stream will automatically flush any outstanding buffers - * in the stream. - * - * Streams will be automatically closed when the last reference - * is dropped, but you might want to call this function to make sure - * resources are released as early as possible. - * - * Some streams might keep the backing store of the stream (e.g. a file - * descriptor) open after the stream is closed. See the documentation for - * the individual stream for details. - * - * On failure the first error that happened will be reported, but the - * close operation will finish as much as possible. A stream that failed - * to close will still return %G_IO_ERROR_CLOSED for all operations. - * Still, it is important to check and report the error to the user, - * otherwise there might be a loss of data as all data might not be written. - * - * If @cancellable is not NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * Cancelling a close will still leave the stream closed, but some streams - * can use a faster close that doesn't block to e.g. check errors. - * - * The default implementation of this method just calls close on the - * individual input/output streams. - * - * Returns: %TRUE on success, %FALSE on failure - * Since: 2.22 - */ - - -/** - * g_io_stream_close_async: - * @stream: a #GIOStream - * @io_priority: the io priority of the request - * @cancellable: (nullable): optional cancellable object - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Requests an asynchronous close of the stream, releasing resources - * related to it. When the operation is finished @callback will be - * called. You can then call g_io_stream_close_finish() to get - * the result of the operation. - * - * For behaviour details see g_io_stream_close(). - * - * The asynchronous methods have a default fallback that uses threads - * to implement asynchronicity, so they are optional for inheriting - * classes. However, if you override one you must override all. - * - * Since: 2.22 - */ - - -/** - * g_io_stream_close_finish: - * @stream: a #GIOStream - * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to - * ignore - * - * Closes a stream. - * - * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_io_stream_get_input_stream: - * @stream: a #GIOStream - * - * Gets the input stream for this object. This is used - * for reading. - * - * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. - * Do not free. - * Since: 2.22 - */ - - -/** - * g_io_stream_get_output_stream: - * @stream: a #GIOStream - * - * Gets the output stream for this object. This is used for - * writing. - * - * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. - * Do not free. - * Since: 2.22 - */ - - -/** - * g_io_stream_has_pending: - * @stream: a #GIOStream - * - * Checks if a stream has pending actions. - * - * Returns: %TRUE if @stream has pending actions. - * Since: 2.22 - */ - - -/** - * g_io_stream_is_closed: - * @stream: a #GIOStream - * - * Checks if a stream is closed. - * - * Returns: %TRUE if the stream is closed. - * Since: 2.22 - */ - - -/** - * g_io_stream_set_pending: - * @stream: a #GIOStream - * @error: a #GError location to store the error occurring, or %NULL to - * ignore - * - * Sets @stream to have actions pending. If the pending flag is - * already set or @stream is closed, it will return %FALSE and set - * @error. - * - * Returns: %TRUE if pending was previously unset and is now set. - * Since: 2.22 - */ - - -/** - * g_io_stream_splice_async: - * @stream1: a #GIOStream. - * @stream2: a #GIOStream. - * @flags: a set of #GIOStreamSpliceFlags. - * @io_priority: the io priority of the request. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. - * - * Asynchronously splice the output stream of @stream1 to the input stream of - * @stream2, and splice the output stream of @stream2 to the input stream of - * @stream1. - * - * When the operation is finished @callback will be called. - * You can then call g_io_stream_splice_finish() to get the - * result of the operation. - * - * Since: 2.28 - */ - - -/** - * g_io_stream_splice_finish: - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes an asynchronous io stream splice operation. - * - * Returns: %TRUE on success, %FALSE otherwise. - * Since: 2.28 - */ - - -/** - * g_keyfile_settings_backend_new: - * @filename: the filename of the keyfile - * @root_path: the path under which all settings keys appear - * @root_group: (nullable): the group name corresponding to - * @root_path, or %NULL - * - * Creates a keyfile-backed #GSettingsBackend. - * - * The filename of the keyfile to use is given by @filename. - * - * All settings read to or written from the backend must fall under the - * path given in @root_path (which must start and end with a slash and - * not contain two consecutive slashes). @root_path may be "/". - * - * If @root_group is non-%NULL then it specifies the name of the keyfile - * group used for keys that are written directly below @root_path. For - * example, if @root_path is "/apps/example/" and @root_group is - * "toplevel", then settings the key "/apps/example/enabled" to a value - * of %TRUE will cause the following to appear in the keyfile: - * - * |[ - * [toplevel] - * enabled=true - * ]| - * - * If @root_group is %NULL then it is not permitted to store keys - * directly below the @root_path. - * - * For keys not stored directly below @root_path (ie: in a sub-path), - * the name of the subpath (with the final slash stripped) is used as - * the name of the keyfile group. To continue the example, if - * "/apps/example/profiles/default/font-size" were set to - * 12 then the following would appear in the keyfile: - * - * |[ - * [profiles/default] - * font-size=12 - * ]| - * - * The backend will refuse writes (and return writability as being - * %FALSE) for keys outside of @root_path and, in the event that - * @root_group is %NULL, also for keys directly under @root_path. - * Writes will also be refused if the backend detects that it has the - * inability to rewrite the keyfile (ie: the containing directory is not - * writable). - * - * There is no checking done for your key namespace clashing with the - * syntax of the key file format. For example, if you have '[' or ']' - * characters in your path names or '=' in your key names you may be in - * trouble. - * - * The backend reads default values from a keyfile called `defaults` in - * the directory specified by the #GKeyfileSettingsBackend:defaults-dir property, - * and a list of locked keys from a text file with the name `locks` in - * the same location. - * - * Returns: (transfer full): a keyfile-backed #GSettingsBackend - */ - - -/** - * g_list_model_get_item: (skip) - * @list: a #GListModel - * @position: the position of the item to fetch - * - * Get the item at @position. If @position is greater than the number of - * items in @list, %NULL is returned. - * - * %NULL is never returned for an index that is smaller than the length - * of the list. See g_list_model_get_n_items(). - * - * Returns: (transfer full) (nullable): the item at @position. - * Since: 2.44 - */ - - -/** - * g_list_model_get_item_type: - * @list: a #GListModel - * - * Gets the type of the items in @list. All items returned from - * g_list_model_get_type() are of that type or a subtype, or are an - * implementation of that interface. - * - * The item type of a #GListModel can not change during the life of the - * model. - * - * Returns: the #GType of the items contained in @list. - * Since: 2.44 - */ - - -/** - * g_list_model_get_n_items: - * @list: a #GListModel - * - * Gets the number of items in @list. - * - * Depending on the model implementation, calling this function may be - * less efficient than iterating the list with increasing values for - * @position until g_list_model_get_item() returns %NULL. - * - * Returns: the number of items in @list. - * Since: 2.44 - */ - - -/** - * g_list_model_get_object: (rename-to g_list_model_get_item) - * @list: a #GListModel - * @position: the position of the item to fetch - * - * Get the item at @position. If @position is greater than the number of - * items in @list, %NULL is returned. - * - * %NULL is never returned for an index that is smaller than the length - * of the list. See g_list_model_get_n_items(). - * - * Returns: (transfer full) (nullable): the object at @position. - * Since: 2.44 - */ - - -/** - * g_list_model_items_changed: - * @list: a #GListModel - * @position: the position at which @list changed - * @removed: the number of items removed - * @added: the number of items added - * - * Emits the #GListModel::items-changed signal on @list. - * - * This function should only be called by classes implementing - * #GListModel. It has to be called after the internal representation - * of @list has been updated, because handlers connected to this signal - * might query the new state of the list. - * - * Implementations must only make changes to the model (as visible to - * its consumer) in places that will not cause problems for that - * consumer. For models that are driven directly by a write API (such - * as #GListStore), changes can be reported in response to uses of that - * API. For models that represent remote data, changes should only be - * made from a fresh mainloop dispatch. It is particularly not - * permitted to make changes in response to a call to the #GListModel - * consumer API. - * - * Stated another way: in general, it is assumed that code making a - * series of accesses to the model via the API, without returning to the - * mainloop, and without calling other code, will continue to view the - * same contents of the model. - * - * Since: 2.44 - */ - - -/** - * g_list_store_append: - * @store: a #GListStore - * @item: (type GObject): the new item - * - * Appends @item to @store. @item must be of type #GListStore:item-type. - * - * This function takes a ref on @item. - * - * Use g_list_store_splice() to append multiple items at the same time - * efficiently. - * - * Since: 2.44 - */ - - -/** - * g_list_store_find: - * @store: a #GListStore - * @item: (type GObject): an item - * @position: (out) (optional): the first position of @item, if it was found. - * - * Looks up the given @item in the list store by looping over the items until - * the first occurrence of @item. If @item was not found, then @position will - * not be set, and this method will return %FALSE. - * - * If you need to compare the two items with a custom comparison function, use - * g_list_store_find_with_equal_func() with a custom #GEqualFunc instead. - * - * Returns: Whether @store contains @item. If it was found, @position will be - * set to the position where @item occurred for the first time. - * Since: 2.64 - */ - - -/** - * g_list_store_find_with_equal_func: - * @store: a #GListStore - * @item: (type GObject): an item - * @equal_func: (scope call): A custom equality check function - * @position: (out) (optional): the first position of @item, if it was found. - * - * Looks up the given @item in the list store by looping over the items and - * comparing them with @compare_func until the first occurrence of @item which - * matches. If @item was not found, then @position will not be set, and this - * method will return %FALSE. - * - * Returns: Whether @store contains @item. If it was found, @position will be - * set to the position where @item occurred for the first time. - * Since: 2.64 - */ - - -/** - * g_list_store_insert: - * @store: a #GListStore - * @position: the position at which to insert the new item - * @item: (type GObject): the new item - * - * Inserts @item into @store at @position. @item must be of type - * #GListStore:item-type or derived from it. @position must be smaller - * than the length of the list, or equal to it to append. - * - * This function takes a ref on @item. - * - * Use g_list_store_splice() to insert multiple items at the same time - * efficiently. - * - * Since: 2.44 - */ - - -/** - * g_list_store_insert_sorted: - * @store: a #GListStore - * @item: (type GObject): the new item - * @compare_func: (scope call): pairwise comparison function for sorting - * @user_data: (closure): user data for @compare_func - * - * Inserts @item into @store at a position to be determined by the - * @compare_func. - * - * The list must already be sorted before calling this function or the - * result is undefined. Usually you would approach this by only ever - * inserting items by way of this function. - * - * This function takes a ref on @item. - * - * Returns: the position at which @item was inserted - * Since: 2.44 - */ - - -/** - * g_list_store_new: - * @item_type: the #GType of items in the list - * - * Creates a new #GListStore with items of type @item_type. @item_type - * must be a subclass of #GObject. - * - * Returns: a new #GListStore - * Since: 2.44 - */ - - -/** - * g_list_store_remove: - * @store: a #GListStore - * @position: the position of the item that is to be removed - * - * Removes the item from @store that is at @position. @position must be - * smaller than the current length of the list. - * - * Use g_list_store_splice() to remove multiple items at the same time - * efficiently. - * - * Since: 2.44 - */ - - -/** - * g_list_store_remove_all: - * @store: a #GListStore - * - * Removes all items from @store. - * - * Since: 2.44 - */ - - -/** - * g_list_store_sort: - * @store: a #GListStore - * @compare_func: (scope call): pairwise comparison function for sorting - * @user_data: (closure): user data for @compare_func - * - * Sort the items in @store according to @compare_func. - * - * Since: 2.46 - */ - - -/** - * g_list_store_splice: - * @store: a #GListStore - * @position: the position at which to make the change - * @n_removals: the number of items to remove - * @additions: (array length=n_additions) (element-type GObject): the items to add - * @n_additions: the number of items to add - * - * Changes @store by removing @n_removals items and adding @n_additions - * items to it. @additions must contain @n_additions items of type - * #GListStore:item-type. %NULL is not permitted. - * - * This function is more efficient than g_list_store_insert() and - * g_list_store_remove(), because it only emits - * #GListModel::items-changed once for the change. - * - * This function takes a ref on each item in @additions. - * - * The parameters @position and @n_removals must be correct (ie: - * @position + @n_removals must be less than or equal to the length of - * the list at the time this function is called). - * - * Since: 2.44 - */ - - -/** - * g_loadable_icon_load: - * @icon: a #GLoadableIcon. - * @size: an integer. - * @type: (out) (optional): a location to store the type of the loaded - * icon, %NULL to ignore. - * @cancellable: (nullable): optional #GCancellable object, %NULL to - * ignore. - * @error: a #GError location to store the error occurring, or %NULL - * to ignore. - * - * Loads a loadable icon. For the asynchronous version of this function, - * see g_loadable_icon_load_async(). - * - * Returns: (transfer full): a #GInputStream to read the icon from. - */ - - -/** - * g_loadable_icon_load_async: - * @icon: a #GLoadableIcon. - * @size: an integer. - * @cancellable: (nullable): 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 - * - * Loads an icon asynchronously. To finish this function, see - * g_loadable_icon_load_finish(). For the synchronous, blocking - * version of this function, see g_loadable_icon_load(). - */ - - -/** - * g_loadable_icon_load_finish: - * @icon: a #GLoadableIcon. - * @res: a #GAsyncResult. - * @type: (out) (optional): a location to store the type of the loaded - * icon, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes an asynchronous icon load started in g_loadable_icon_load_async(). - * - * Returns: (transfer full): a #GInputStream to read the icon from. - */ - - -/** - * g_local_vfs_new: - * - * Returns a new #GVfs handle for a local vfs. - * - * Returns: a new #GVfs handle. - */ - - -/** - * g_memory_input_stream_add_bytes: - * @stream: a #GMemoryInputStream - * @bytes: input data - * - * Appends @bytes to data that can be read from the input stream. - * - * Since: 2.34 - */ - - -/** - * g_memory_input_stream_add_data: - * @stream: a #GMemoryInputStream - * @data: (array length=len) (element-type guint8) (transfer full): input data - * @len: length of the data, may be -1 if @data is a nul-terminated string - * @destroy: (nullable): function that is called to free @data, or %NULL - * - * Appends @data to data that can be read from the input stream - */ - - -/** - * g_memory_input_stream_new: - * - * Creates a new empty #GMemoryInputStream. - * - * Returns: a new #GInputStream - */ - - -/** - * g_memory_input_stream_new_from_bytes: - * @bytes: a #GBytes - * - * Creates a new #GMemoryInputStream with data from the given @bytes. - * - * Returns: new #GInputStream read from @bytes - * Since: 2.34 - */ - - -/** - * g_memory_input_stream_new_from_data: - * @data: (array length=len) (element-type guint8) (transfer full): input data - * @len: length of the data, may be -1 if @data is a nul-terminated string - * @destroy: (nullable): function that is called to free @data, or %NULL - * - * Creates a new #GMemoryInputStream with data in memory of a given size. - * - * Returns: new #GInputStream read from @data of @len bytes. - */ - - -/** - * g_memory_monitor_dup_default: - * - * Gets a reference to the default #GMemoryMonitor for the system. - * - * Returns: (not nullable) (transfer full): a new reference to the default #GMemoryMonitor - * Since: 2.64 - */ - - -/** - * g_memory_output_stream_get_data: - * @ostream: a #GMemoryOutputStream - * - * Gets any loaded data from the @ostream. - * - * Note that the returned pointer may become invalid on the next - * write or truncate operation on the stream. - * - * Returns: (transfer none): pointer to the stream's data, or %NULL if the data - * has been stolen - */ - - -/** - * g_memory_output_stream_get_data_size: - * @ostream: a #GMemoryOutputStream - * - * Returns the number of bytes from the start up to including the last - * byte written in the stream that has not been truncated away. - * - * Returns: the number of bytes written to the stream - * Since: 2.18 - */ - - -/** - * g_memory_output_stream_get_size: - * @ostream: a #GMemoryOutputStream - * - * Gets the size of the currently allocated data area (available from - * g_memory_output_stream_get_data()). - * - * You probably don't want to use this function on resizable streams. - * See g_memory_output_stream_get_data_size() instead. For resizable - * streams the size returned by this function is an implementation - * detail and may be change at any time in response to operations on the - * stream. - * - * If the stream is fixed-sized (ie: no realloc was passed to - * g_memory_output_stream_new()) then this is the maximum size of the - * stream and further writes will return %G_IO_ERROR_NO_SPACE. - * - * In any case, if you want the number of bytes currently written to the - * stream, use g_memory_output_stream_get_data_size(). - * - * Returns: the number of bytes allocated for the data buffer - */ - - -/** - * g_memory_output_stream_new: (skip) - * @data: (nullable): pointer to a chunk of memory to use, or %NULL - * @size: the size of @data - * @realloc_function: (nullable): a function with realloc() semantics (like g_realloc()) - * to be called when @data needs to be grown, or %NULL - * @destroy_function: (nullable): a function to be called on @data when the stream is - * finalized, or %NULL - * - * Creates a new #GMemoryOutputStream. - * - * In most cases this is not the function you want. See - * g_memory_output_stream_new_resizable() instead. - * - * If @data is non-%NULL, the stream will use that for its internal storage. - * - * If @realloc_fn is non-%NULL, it will be used for resizing the internal - * storage when necessary and the stream will be considered resizable. - * In that case, the stream will start out being (conceptually) empty. - * @size is used only as a hint for how big @data is. Specifically, - * seeking to the end of a newly-created stream will seek to zero, not - * @size. Seeking past the end of the stream and then writing will - * introduce a zero-filled gap. - * - * If @realloc_fn is %NULL then the stream is fixed-sized. Seeking to - * the end will seek to @size exactly. Writing past the end will give - * an 'out of space' error. Attempting to seek past the end will fail. - * Unlike the resizable case, seeking to an offset within the stream and - * writing will preserve the bytes passed in as @data before that point - * and will return them as part of g_memory_output_stream_steal_data(). - * If you intend to seek you should probably therefore ensure that @data - * is properly initialised. - * - * It is probably only meaningful to provide @data and @size in the case - * that you want a fixed-sized stream. Put another way: if @realloc_fn - * is non-%NULL then it makes most sense to give @data as %NULL and - * @size as 0 (allowing #GMemoryOutputStream to do the initial - * allocation for itself). - * - * |[ - * // a stream that can grow - * stream = g_memory_output_stream_new (NULL, 0, realloc, free); - * - * // another stream that can grow - * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); - * - * // a fixed-size stream - * data = malloc (200); - * stream3 = g_memory_output_stream_new (data, 200, NULL, free); - * ]| - * - * Returns: A newly created #GMemoryOutputStream object. - */ - - -/** - * 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 - * - * Returns data from the @ostream as a #GBytes. @ostream must be - * closed before calling this function. - * - * Returns: (transfer full): the stream's data - * Since: 2.34 - */ - - -/** - * g_memory_output_stream_steal_data: - * @ostream: a #GMemoryOutputStream - * - * Gets any loaded data from the @ostream. Ownership of the data - * is transferred to the caller; when no longer needed it must be - * freed using the free function set in @ostream's - * #GMemoryOutputStream:destroy-function property. - * - * @ostream must be closed before calling this function. - * - * Returns: (transfer full): the stream's data, or %NULL if it has previously - * been stolen - * Since: 2.26 - */ - - -/** - * g_memory_settings_backend_new: - * - * Creates a memory-backed #GSettingsBackend. - * - * This backend allows changes to settings, but does not write them - * to any backing storage, so the next time you run your application, - * the memory backend will start out with the default values again. - * - * Returns: (transfer full): a newly created #GSettingsBackend - * Since: 2.28 - */ - - -/** - * g_menu_append: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @detailed_action: (nullable): the detailed action string, or %NULL - * - * Convenience function for appending a normal menu item to the end of - * @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more - * flexible alternative. - * - * Since: 2.32 - */ - - -/** - * g_menu_append_item: - * @menu: a #GMenu - * @item: a #GMenuItem to append - * - * Appends @item to the end of @menu. - * - * See g_menu_insert_item() for more information. - * - * Since: 2.32 - */ - - -/** - * g_menu_append_section: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @section: a #GMenuModel with the items of the section - * - * Convenience function for appending a section menu item to the end of - * @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a - * more flexible alternative. - * - * Since: 2.32 - */ - - -/** - * g_menu_append_submenu: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @submenu: a #GMenuModel with the items of the submenu - * - * Convenience function for appending a submenu menu item to the end of - * @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a - * more flexible alternative. - * - * Since: 2.32 - */ - - -/** - * g_menu_attribute_iter_get_name: - * @iter: a #GMenuAttributeIter - * - * Gets the name of the attribute at the current iterator position, as - * a string. - * - * The iterator is not advanced. - * - * Returns: the name of the attribute - * Since: 2.32 - */ - - -/** - * g_menu_attribute_iter_get_next: - * @iter: a #GMenuAttributeIter - * @out_name: (out) (optional) (transfer none): the type of the attribute - * @value: (out) (optional) (transfer full): the attribute value - * - * This function combines g_menu_attribute_iter_next() with - * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value(). - * - * First the iterator is advanced to the next (possibly first) attribute. - * If that fails, then %FALSE is returned and there are no other - * effects. - * - * If successful, @name and @value are set to the name and value of the - * attribute that has just been advanced to. At this point, - * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will - * return the same values again. - * - * The value returned in @name remains valid for as long as the iterator - * remains at the current position. The value returned in @value must - * be unreffed using g_variant_unref() when it is no longer in use. - * - * Returns: %TRUE on success, or %FALSE if there is no additional - * attribute - * Since: 2.32 - */ - - -/** - * g_menu_attribute_iter_get_value: - * @iter: a #GMenuAttributeIter - * - * Gets the value of the attribute at the current iterator position. - * - * The iterator is not advanced. - * - * Returns: (transfer full): the value of the current attribute - * Since: 2.32 - */ - - -/** - * g_menu_attribute_iter_next: - * @iter: a #GMenuAttributeIter - * - * Attempts to advance the iterator to the next (possibly first) - * attribute. - * - * %TRUE is returned on success, or %FALSE if there are no more - * attributes. - * - * You must call this function when you first acquire the iterator - * to advance it to the first attribute (and determine if the first - * attribute exists at all). - * - * Returns: %TRUE on success, or %FALSE when there are no more attributes - * Since: 2.32 - */ - - -/** - * g_menu_freeze: - * @menu: a #GMenu - * - * Marks @menu as frozen. - * - * After the menu is frozen, it is an error to attempt to make any - * changes to it. In effect this means that the #GMenu API must no - * longer be used. - * - * This function causes g_menu_model_is_mutable() to begin returning - * %FALSE, which has some positive performance implications. - * - * Since: 2.32 - */ - - -/** - * g_menu_insert: - * @menu: a #GMenu - * @position: the position at which to insert the item - * @label: (nullable): the section label, or %NULL - * @detailed_action: (nullable): the detailed action string, or %NULL - * - * Convenience function for inserting a normal menu item into @menu. - * Combine g_menu_item_new() and g_menu_insert_item() for a more flexible - * alternative. - * - * Since: 2.32 - */ - - -/** - * g_menu_insert_item: - * @menu: a #GMenu - * @position: the position at which to insert the item - * @item: the #GMenuItem to insert - * - * Inserts @item into @menu. - * - * The "insertion" is actually done by copying all of the attribute and - * link values of @item and using them to form a new item within @menu. - * As such, @item itself is not really inserted, but rather, a menu item - * that is exactly the same as the one presently described by @item. - * - * This means that @item is essentially useless after the insertion - * occurs. Any changes you make to it are ignored unless it is inserted - * again (at which point its updated values will be copied). - * - * You should probably just free @item once you're done. - * - * There are many convenience functions to take care of common cases. - * See g_menu_insert(), g_menu_insert_section() and - * g_menu_insert_submenu() as well as "prepend" and "append" variants of - * each of these functions. - * - * Since: 2.32 - */ - - -/** - * g_menu_insert_section: - * @menu: a #GMenu - * @position: the position at which to insert the item - * @label: (nullable): the section label, or %NULL - * @section: a #GMenuModel with the items of the section - * - * Convenience function for inserting a section menu item into @menu. - * Combine g_menu_item_new_section() and g_menu_insert_item() for a more - * flexible alternative. - * - * Since: 2.32 - */ - - -/** - * g_menu_insert_submenu: - * @menu: a #GMenu - * @position: the position at which to insert the item - * @label: (nullable): the section label, or %NULL - * @submenu: a #GMenuModel with the items of the submenu - * - * Convenience function for inserting a submenu menu item into @menu. - * Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more - * flexible alternative. - * - * Since: 2.32 - */ - - -/** - * g_menu_item_get_attribute: - * @menu_item: a #GMenuItem - * @attribute: the attribute name to query - * @format_string: a #GVariant format string - * @...: positional parameters, as per @format_string - * - * Queries the named @attribute on @menu_item. - * - * If the attribute exists and matches the #GVariantType corresponding - * to @format_string then @format_string is used to deconstruct the - * value into the positional parameters and %TRUE is returned. - * - * If the attribute does not exist, or it does exist but has the wrong - * type, then the positional parameters are ignored and %FALSE is - * returned. - * - * Returns: %TRUE if the named attribute was found with the expected - * type - * Since: 2.34 - */ - - -/** - * g_menu_item_get_attribute_value: - * @menu_item: a #GMenuItem - * @attribute: the attribute name to query - * @expected_type: (nullable): the expected type of the attribute - * - * Queries the named @attribute on @menu_item. - * - * If @expected_type is specified and the attribute does not have this - * type, %NULL is returned. %NULL is also returned if the attribute - * simply does not exist. - * - * Returns: (nullable) (transfer full): the attribute value, or %NULL - * Since: 2.34 - */ - - -/** - * g_menu_item_get_link: - * @menu_item: a #GMenuItem - * @link: the link name to query - * - * Queries the named @link on @menu_item. - * - * Returns: (nullable) (transfer full): the link, or %NULL - * Since: 2.34 - */ - - -/** - * g_menu_item_new: - * @label: (nullable): the section label, or %NULL - * @detailed_action: (nullable): the detailed action string, or %NULL - * - * Creates a new #GMenuItem. - * - * If @label is non-%NULL it is used to set the "label" attribute of the - * new item. - * - * If @detailed_action is non-%NULL it is used to set the "action" and - * possibly the "target" attribute of the new item. See - * g_menu_item_set_detailed_action() for more information. - * - * Returns: a new #GMenuItem - * Since: 2.32 - */ - - -/** - * g_menu_item_new_from_model: - * @model: a #GMenuModel - * @item_index: the index of an item in @model - * - * Creates a #GMenuItem as an exact copy of an existing menu item in a - * #GMenuModel. - * - * @item_index must be valid (ie: be sure to call - * g_menu_model_get_n_items() first). - * - * Returns: a new #GMenuItem. - * Since: 2.34 - */ - - -/** - * g_menu_item_new_section: - * @label: (nullable): the section label, or %NULL - * @section: a #GMenuModel with the items of the section - * - * Creates a new #GMenuItem representing a section. - * - * This is a convenience API around g_menu_item_new() and - * g_menu_item_set_section(). - * - * The effect of having one menu appear as a section of another is - * exactly as it sounds: the items from @section become a direct part of - * the menu that @menu_item is added to. - * - * Visual separation is typically displayed between two non-empty - * sections. If @label is non-%NULL then it will be encorporated into - * this visual indication. This allows for labeled subsections of a - * menu. - * - * As a simple example, consider a typical "Edit" menu from a simple - * program. It probably contains an "Undo" and "Redo" item, followed by - * a separator, followed by "Cut", "Copy" and "Paste". - * - * This would be accomplished by creating three #GMenu instances. The - * first would be populated with the "Undo" and "Redo" items, and the - * second with the "Cut", "Copy" and "Paste" items. The first and - * second menus would then be added as submenus of the third. In XML - * format, this would look something like the following: - * |[ - * - *
- * - * - *
- *
- * - * - * - *
- * - * ]| - * - * The following example is exactly equivalent. It is more illustrative - * of the exact relationship between the menus and items (keeping in - * mind that the 'link' element defines a new menu that is linked to the - * containing one). The style of the second example is more verbose and - * difficult to read (and therefore not recommended except for the - * purpose of understanding what is really going on). - * |[ - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * ]| - * - * Returns: a new #GMenuItem - * Since: 2.32 - */ - - -/** - * g_menu_item_new_submenu: - * @label: (nullable): the section label, or %NULL - * @submenu: a #GMenuModel with the items of the submenu - * - * Creates a new #GMenuItem representing a submenu. - * - * This is a convenience API around g_menu_item_new() and - * g_menu_item_set_submenu(). - * - * Returns: a new #GMenuItem - * Since: 2.32 - */ - - -/** - * g_menu_item_set_action_and_target: - * @menu_item: a #GMenuItem - * @action: (nullable): the name of the action for this item - * @format_string: (nullable): a GVariant format string - * @...: positional parameters, as per @format_string - * - * Sets or unsets the "action" and "target" attributes of @menu_item. - * - * If @action is %NULL then both the "action" and "target" attributes - * are unset (and @format_string is ignored along with the positional - * parameters). - * - * If @action is non-%NULL then the "action" attribute is set. - * @format_string is then inspected. If it is non-%NULL then the proper - * position parameters are collected to create a #GVariant instance to - * use as the target value. If it is %NULL then the positional - * parameters are ignored and the "target" attribute is unset. - * - * See also g_menu_item_set_action_and_target_value() for an equivalent - * call that directly accepts a #GVariant. See - * g_menu_item_set_detailed_action() for a more convenient version that - * works with string-typed targets. - * - * See also g_menu_item_set_action_and_target_value() for a - * description of the semantics of the action and target attributes. - * - * Since: 2.32 - */ - - -/** - * g_menu_item_set_action_and_target_value: - * @menu_item: a #GMenuItem - * @action: (nullable): the name of the action for this item - * @target_value: (nullable): a #GVariant to use as the action target - * - * Sets or unsets the "action" and "target" attributes of @menu_item. - * - * If @action is %NULL then both the "action" and "target" attributes - * are unset (and @target_value is ignored). - * - * If @action is non-%NULL then the "action" attribute is set. The - * "target" attribute is then set to the value of @target_value if it is - * non-%NULL or unset otherwise. - * - * Normal menu items (ie: not submenu, section or other custom item - * types) are expected to have the "action" attribute set to identify - * the action that they are associated with. The state type of the - * action help to determine the disposition of the menu item. See - * #GAction and #GActionGroup for an overview of actions. - * - * In general, clicking on the menu item will result in activation of - * the named action with the "target" attribute given as the parameter - * to the action invocation. If the "target" attribute is not set then - * the action is invoked with no parameter. - * - * If the action has no state then the menu item is usually drawn as a - * plain menu item (ie: with no additional decoration). - * - * If the action has a boolean state then the menu item is usually drawn - * as a toggle menu item (ie: with a checkmark or equivalent - * indication). The item should be marked as 'toggled' or 'checked' - * when the boolean state is %TRUE. - * - * If the action has a string state then the menu item is usually drawn - * as a radio menu item (ie: with a radio bullet or equivalent - * indication). The item should be marked as 'selected' when the string - * state is equal to the value of the @target property. - * - * See g_menu_item_set_action_and_target() or - * g_menu_item_set_detailed_action() for two equivalent calls that are - * probably more convenient for most uses. - * - * Since: 2.32 - */ - - -/** - * g_menu_item_set_attribute: - * @menu_item: a #GMenuItem - * @attribute: the attribute to set - * @format_string: (nullable): a #GVariant format string, or %NULL - * @...: positional parameters, as per @format_string - * - * Sets or unsets an attribute on @menu_item. - * - * The attribute to set or unset is specified by @attribute. This - * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL, - * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom - * attribute name. - * Attribute names are restricted to lowercase characters, numbers - * and '-'. Furthermore, the names must begin with a lowercase character, - * must not end with a '-', and must not contain consecutive dashes. - * - * If @format_string is non-%NULL then the proper position parameters - * are collected to create a #GVariant instance to use as the attribute - * value. If it is %NULL then the positional parameterrs are ignored - * and the named attribute is unset. - * - * See also g_menu_item_set_attribute_value() for an equivalent call - * that directly accepts a #GVariant. - * - * Since: 2.32 - */ - - -/** - * g_menu_item_set_attribute_value: - * @menu_item: a #GMenuItem - * @attribute: the attribute to set - * @value: (nullable): a #GVariant to use as the value, or %NULL - * - * Sets or unsets an attribute on @menu_item. - * - * The attribute to set or unset is specified by @attribute. This - * can be one of the standard attribute names %G_MENU_ATTRIBUTE_LABEL, - * %G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, or a custom - * attribute name. - * Attribute names are restricted to lowercase characters, numbers - * and '-'. Furthermore, the names must begin with a lowercase character, - * must not end with a '-', and must not contain consecutive dashes. - * - * must consist only of lowercase - * ASCII characters, digits and '-'. - * - * If @value is non-%NULL then it is used as the new value for the - * attribute. If @value is %NULL then the attribute is unset. If - * the @value #GVariant is floating, it is consumed. - * - * See also g_menu_item_set_attribute() for a more convenient way to do - * the same. - * - * Since: 2.32 - */ - - -/** - * g_menu_item_set_detailed_action: - * @menu_item: a #GMenuItem - * @detailed_action: the "detailed" action string - * - * Sets the "action" and possibly the "target" attribute of @menu_item. - * - * 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 - * slightly less convenient) alternatives. - * - * See also g_menu_item_set_action_and_target_value() for a description of - * the semantics of the action and target attributes. - * - * Since: 2.32 - */ - - -/** - * 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: (nullable): the label to set, or %NULL to unset - * - * Sets or unsets the "label" attribute of @menu_item. - * - * If @label is non-%NULL it is used as the label for the menu item. If - * it is %NULL then the label attribute is unset. - * - * Since: 2.32 - */ - - -/** - * g_menu_item_set_link: - * @menu_item: a #GMenuItem - * @link: type of link to establish or unset - * @model: (nullable): the #GMenuModel to link to (or %NULL to unset) - * - * Creates a link from @menu_item to @model if non-%NULL, or unsets it. - * - * Links are used to establish a relationship between a particular menu - * item and another menu. For example, %G_MENU_LINK_SUBMENU is used to - * associate a submenu with a particular menu item, and %G_MENU_LINK_SECTION - * is used to create a section. Other types of link can be used, but there - * is no guarantee that clients will be able to make sense of them. - * Link types are restricted to lowercase characters, numbers - * and '-'. Furthermore, the names must begin with a lowercase character, - * must not end with a '-', and must not contain consecutive dashes. - * - * Since: 2.32 - */ - - -/** - * g_menu_item_set_section: - * @menu_item: a #GMenuItem - * @section: (nullable): a #GMenuModel, or %NULL - * - * Sets or unsets the "section" link of @menu_item to @section. - * - * The effect of having one menu appear as a section of another is - * exactly as it sounds: the items from @section become a direct part of - * the menu that @menu_item is added to. See g_menu_item_new_section() - * for more information about what it means for a menu item to be a - * section. - * - * Since: 2.32 - */ - - -/** - * g_menu_item_set_submenu: - * @menu_item: a #GMenuItem - * @submenu: (nullable): a #GMenuModel, or %NULL - * - * Sets or unsets the "submenu" link of @menu_item to @submenu. - * - * If @submenu is non-%NULL, it is linked to. If it is %NULL then the - * link is unset. - * - * The effect of having one menu appear as a submenu of another is - * exactly as it sounds. - * - * Since: 2.32 - */ - - -/** - * g_menu_link_iter_get_name: - * @iter: a #GMenuLinkIter - * - * Gets the name of the link at the current iterator position. - * - * The iterator is not advanced. - * - * Returns: the type of the link - * Since: 2.32 - */ - - -/** - * g_menu_link_iter_get_next: - * @iter: a #GMenuLinkIter - * @out_link: (out) (optional) (transfer none): the name of the link - * @value: (out) (optional) (transfer full): the linked #GMenuModel - * - * This function combines g_menu_link_iter_next() with - * g_menu_link_iter_get_name() and g_menu_link_iter_get_value(). - * - * First the iterator is advanced to the next (possibly first) link. - * If that fails, then %FALSE is returned and there are no other effects. - * - * If successful, @out_link and @value are set to the name and #GMenuModel - * of the link that has just been advanced to. At this point, - * g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the - * same values again. - * - * The value returned in @out_link remains valid for as long as the iterator - * remains at the current position. The value returned in @value must - * be unreffed using g_object_unref() when it is no longer in use. - * - * Returns: %TRUE on success, or %FALSE if there is no additional link - * Since: 2.32 - */ - - -/** - * g_menu_link_iter_get_value: - * @iter: a #GMenuLinkIter - * - * Gets the linked #GMenuModel at the current iterator position. - * - * The iterator is not advanced. - * - * Returns: (transfer full): the #GMenuModel that is linked to - * Since: 2.32 - */ - - -/** - * g_menu_link_iter_next: - * @iter: a #GMenuLinkIter - * - * Attempts to advance the iterator to the next (possibly first) - * link. - * - * %TRUE is returned on success, or %FALSE if there are no more links. - * - * You must call this function when you first acquire the iterator to - * advance it to the first link (and determine if the first link exists - * at all). - * - * Returns: %TRUE on success, or %FALSE when there are no more links - * Since: 2.32 - */ - - -/** - * g_menu_model_get_item_attribute: - * @model: a #GMenuModel - * @item_index: the index of the item - * @attribute: the attribute to query - * @format_string: a #GVariant format string - * @...: positional parameters, as per @format_string - * - * Queries item at position @item_index in @model for the attribute - * specified by @attribute. - * - * If the attribute exists and matches the #GVariantType corresponding - * to @format_string then @format_string is used to deconstruct the - * value into the positional parameters and %TRUE is returned. - * - * If the attribute does not exist, or it does exist but has the wrong - * type, then the positional parameters are ignored and %FALSE is - * returned. - * - * This function is a mix of g_menu_model_get_item_attribute_value() and - * g_variant_get(), followed by a g_variant_unref(). As such, - * @format_string must make a complete copy of the data (since the - * #GVariant may go away after the call to g_variant_unref()). In - * particular, no '&' characters are allowed in @format_string. - * - * Returns: %TRUE if the named attribute was found with the expected - * type - * Since: 2.32 - */ - - -/** - * g_menu_model_get_item_attribute_value: - * @model: a #GMenuModel - * @item_index: the index of the item - * @attribute: the attribute to query - * @expected_type: (nullable): the expected type of the attribute, or - * %NULL - * - * Queries the item at position @item_index in @model for the attribute - * specified by @attribute. - * - * If @expected_type is non-%NULL then it specifies the expected type of - * the attribute. If it is %NULL then any type will be accepted. - * - * If the attribute exists and matches @expected_type (or if the - * expected type is unspecified) then the value is returned. - * - * If the attribute does not exist, or does not match the expected type - * then %NULL is returned. - * - * Returns: (nullable) (transfer full): the value of the attribute - * Since: 2.32 - */ - - -/** - * g_menu_model_get_item_link: - * @model: a #GMenuModel - * @item_index: the index of the item - * @link: the link to query - * - * Queries the item at position @item_index in @model for the link - * specified by @link. - * - * If the link exists, the linked #GMenuModel is returned. If the link - * does not exist, %NULL is returned. - * - * Returns: (nullable) (transfer full): the linked #GMenuModel, or %NULL - * Since: 2.32 - */ - - -/** - * g_menu_model_get_n_items: - * @model: a #GMenuModel - * - * Query the number of items in @model. - * - * Returns: the number of items - * Since: 2.32 - */ - - -/** - * g_menu_model_is_mutable: - * @model: a #GMenuModel - * - * Queries if @model is mutable. - * - * An immutable #GMenuModel will never emit the #GMenuModel::items-changed - * signal. Consumers of the model may make optimisations accordingly. - * - * Returns: %TRUE if the model is mutable (ie: "items-changed" may be - * emitted). - * Since: 2.32 - */ - - -/** - * g_menu_model_items_changed: - * @model: a #GMenuModel - * @position: the position of the change - * @removed: the number of items removed - * @added: the number of items added - * - * Requests emission of the #GMenuModel::items-changed signal on @model. - * - * This function should never be called except by #GMenuModel - * subclasses. Any other calls to this function will very likely lead - * to a violation of the interface of the model. - * - * The implementation should update its internal representation of the - * menu before emitting the signal. The implementation should further - * expect to receive queries about the new state of the menu (and - * particularly added menu items) while signal handlers are running. - * - * The implementation must dispatch this call directly from a mainloop - * entry and not in response to calls -- particularly those from the - * #GMenuModel API. Said another way: the menu must not change while - * user code is running without returning to the mainloop. - * - * Since: 2.32 - */ - - -/** - * g_menu_model_iterate_item_attributes: - * @model: a #GMenuModel - * @item_index: the index of the item - * - * Creates a #GMenuAttributeIter to iterate over the attributes of - * the item at position @item_index in @model. - * - * You must free the iterator with g_object_unref() when you are done. - * - * Returns: (transfer full): a new #GMenuAttributeIter - * Since: 2.32 - */ - - -/** - * g_menu_model_iterate_item_links: - * @model: a #GMenuModel - * @item_index: the index of the item - * - * Creates a #GMenuLinkIter to iterate over the links of the item at - * position @item_index in @model. - * - * You must free the iterator with g_object_unref() when you are done. - * - * Returns: (transfer full): a new #GMenuLinkIter - * Since: 2.32 - */ - - -/** - * g_menu_new: - * - * Creates a new #GMenu. - * - * The new menu has no items. - * - * Returns: a new #GMenu - * Since: 2.32 - */ - - -/** - * g_menu_prepend: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @detailed_action: (nullable): the detailed action string, or %NULL - * - * Convenience function for prepending a normal menu item to the start - * of @menu. Combine g_menu_item_new() and g_menu_insert_item() for a more - * flexible alternative. - * - * Since: 2.32 - */ - - -/** - * g_menu_prepend_item: - * @menu: a #GMenu - * @item: a #GMenuItem to prepend - * - * Prepends @item to the start of @menu. - * - * See g_menu_insert_item() for more information. - * - * Since: 2.32 - */ - - -/** - * g_menu_prepend_section: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @section: a #GMenuModel with the items of the section - * - * Convenience function for prepending a section menu item to the start - * of @menu. Combine g_menu_item_new_section() and g_menu_insert_item() for - * a more flexible alternative. - * - * Since: 2.32 - */ - - -/** - * g_menu_prepend_submenu: - * @menu: a #GMenu - * @label: (nullable): the section label, or %NULL - * @submenu: a #GMenuModel with the items of the submenu - * - * Convenience function for prepending a submenu menu item to the start - * of @menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for - * a more flexible alternative. - * - * Since: 2.32 - */ - - -/** - * g_menu_remove: - * @menu: a #GMenu - * @position: the position of the item to remove - * - * Removes an item from the menu. - * - * @position gives the index of the item to remove. - * - * It is an error if position is not in range the range from 0 to one - * less than the number of items in the menu. - * - * It is not possible to remove items by identity since items are added - * to the menu simply by copying their links and attributes (ie: - * identity of the item itself is not preserved). - * - * Since: 2.32 - */ - - -/** - * g_menu_remove_all: - * @menu: a #GMenu - * - * Removes all items in the menu. - * - * Since: 2.38 - */ - - -/** - * g_mount_can_eject: - * @mount: a #GMount. - * - * Checks if @mount can be ejected. - * - * Returns: %TRUE if the @mount can be ejected. - */ - - -/** - * g_mount_can_unmount: - * @mount: a #GMount. - * - * Checks if @mount can be unmounted. - * - * Returns: %TRUE if the @mount can be unmounted. - */ - - -/** - * g_mount_eject: - * @mount: a #GMount. - * @flags: flags affecting the unmount if required for eject - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. - * - * Ejects a mount. This is an asynchronous operation, and is - * finished by calling g_mount_eject_finish() with the @mount - * and #GAsyncResult data returned in the @callback. - * - * Deprecated: 2.22: Use g_mount_eject_with_operation() instead. - */ - - -/** - * g_mount_eject_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes ejecting a mount. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. - * - * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise. - * Deprecated: 2.22: Use g_mount_eject_with_operation_finish() instead. - */ - - -/** - * g_mount_eject_with_operation: - * @mount: a #GMount. - * @flags: flags affecting the unmount if required for eject - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. - * - * Ejects a mount. This is an asynchronous operation, and is - * finished by calling g_mount_eject_with_operation_finish() with the @mount - * and #GAsyncResult data returned in the @callback. - * - * Since: 2.22 - */ - - -/** - * g_mount_eject_with_operation_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes ejecting a mount. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. - * - * Returns: %TRUE if the mount was successfully ejected. %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_mount_get_default_location: - * @mount: a #GMount. - * - * Gets the default location of @mount. The default location of the given - * @mount is a path that reflects the main entry point for the user (e.g. - * the home directory, or the root of the volume). - * - * Returns: (transfer full): a #GFile. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. - */ - - -/** - * g_mount_get_drive: - * @mount: a #GMount. - * - * Gets the drive for the @mount. - * - * This is a convenience method for getting the #GVolume and then - * using that object to get the #GDrive. - * - * Returns: (transfer full) (nullable): a #GDrive or %NULL if @mount is not - * associated with a volume or a drive. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. - */ - - -/** - * g_mount_get_icon: - * @mount: a #GMount. - * - * Gets the icon for @mount. - * - * Returns: (transfer full): a #GIcon. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. - */ - - -/** - * g_mount_get_name: - * @mount: a #GMount. - * - * Gets the name of @mount. - * - * Returns: the name for the given @mount. - * The returned string should be freed with g_free() - * when no longer needed. - */ - - -/** - * g_mount_get_root: - * @mount: a #GMount. - * - * Gets the root directory on @mount. - * - * Returns: (transfer full): a #GFile. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. - */ - - -/** - * g_mount_get_sort_key: - * @mount: A #GMount. - * - * Gets the sort key for @mount, if any. - * - * Returns: (nullable): Sorting key for @mount or %NULL if no such key is available. - * Since: 2.32 - */ - - -/** - * g_mount_get_symbolic_icon: - * @mount: a #GMount. - * - * Gets the symbolic icon for @mount. - * - * Returns: (transfer full): a #GIcon. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. - * Since: 2.34 - */ - - -/** - * g_mount_get_uuid: - * @mount: a #GMount. - * - * Gets the UUID for the @mount. The reference is typically based on - * the file system UUID for the mount in question and should be - * considered an opaque string. Returns %NULL if there is no UUID - * available. - * - * Returns: (nullable) (transfer full): the UUID for @mount or %NULL if no UUID - * can be computed. - * The returned string should be freed with g_free() - * when no longer needed. - */ - - -/** - * g_mount_get_volume: - * @mount: a #GMount. - * - * Gets the volume for the @mount. - * - * Returns: (transfer full) (nullable): a #GVolume or %NULL if @mount is not - * associated with a volume. - * The returned object should be unreffed with - * g_object_unref() when no longer needed. - */ - - -/** - * g_mount_guess_content_type: - * @mount: a #GMount - * @force_rescan: Whether to force a rescan of the content. - * Otherwise a cached result will be used if available - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback - * @user_data: user data passed to @callback - * - * Tries to guess the type of content stored on @mount. Returns one or - * more textual identifiers of well-known content types (typically - * prefixed with "x-content/"), e.g. x-content/image-dcf for camera - * memory cards. See the - * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) - * specification for more on x-content types. - * - * This is an asynchronous operation (see - * g_mount_guess_content_type_sync() for the synchronous version), and - * is finished by calling g_mount_guess_content_type_finish() with the - * @mount and #GAsyncResult data returned in the @callback. - * - * Since: 2.18 - */ - - -/** - * g_mount_guess_content_type_finish: - * @mount: a #GMount - * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to - * ignore - * - * Finishes guessing content types of @mount. If any errors occurred - * during the operation, @error will be set to contain the errors and - * %FALSE will be returned. In particular, you may get an - * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content - * guessing. - * - * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. - * Caller should free this array with g_strfreev() when done with it. - * Since: 2.18 - */ - - -/** - * g_mount_guess_content_type_sync: - * @mount: a #GMount - * @force_rescan: Whether to force a rescan of the content. - * Otherwise a cached result will be used if available - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @error: a #GError location to store the error occurring, or %NULL to - * ignore - * - * Tries to guess the type of content stored on @mount. Returns one or - * more textual identifiers of well-known content types (typically - * prefixed with "x-content/"), e.g. x-content/image-dcf for camera - * memory cards. See the - * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) - * specification for more on x-content types. - * - * This is a synchronous operation and as such may block doing IO; - * see g_mount_guess_content_type() for the asynchronous version. - * - * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. - * Caller should free this array with g_strfreev() when done with it. - * Since: 2.18 - */ - - -/** - * g_mount_is_shadowed: - * @mount: A #GMount. - * - * Determines if @mount is shadowed. Applications or libraries should - * avoid displaying @mount in the user interface if it is shadowed. - * - * A mount is said to be shadowed if there exists one or more user - * visible objects (currently #GMount objects) with a root that is - * inside the root of @mount. - * - * One application of shadow mounts is when exposing a single file - * system that is used to address several logical volumes. In this - * situation, a #GVolumeMonitor implementation would create two - * #GVolume objects (for example, one for the camera functionality of - * the device and one for a SD card reader on the device) with - * activation URIs `gphoto2://[usb:001,002]/store1/` - * and `gphoto2://[usb:001,002]/store2/`. When the - * underlying mount (with root - * `gphoto2://[usb:001,002]/`) is mounted, said - * #GVolumeMonitor implementation would create two #GMount objects - * (each with their root matching the corresponding volume activation - * root) that would shadow the original mount. - * - * The proxy monitor in GVfs 2.26 and later, automatically creates and - * manage shadow mounts (and shadows the underlying mount) if the - * activation root on a #GVolume is set. - * - * Returns: %TRUE if @mount is shadowed. - * Since: 2.20 - */ - - -/** - * g_mount_operation_get_anonymous: - * @op: a #GMountOperation. - * - * Check to see whether the mount operation is being used - * for an anonymous user. - * - * Returns: %TRUE if mount operation is anonymous. - */ - - -/** - * g_mount_operation_get_choice: - * @op: a #GMountOperation. - * - * Gets a choice from the mount operation. - * - * Returns: an integer containing an index of the user's choice from - * the choice's list, or `0`. - */ - - -/** - * g_mount_operation_get_domain: - * @op: a #GMountOperation. - * - * Gets the domain of the mount operation. - * - * Returns: (nullable): a string set to the domain. - */ - - -/** - * g_mount_operation_get_is_tcrypt_hidden_volume: - * @op: a #GMountOperation. - * - * Check to see whether the mount operation is being used - * for a TCRYPT hidden volume. - * - * Returns: %TRUE if mount operation is for hidden volume. - * Since: 2.58 - */ - - -/** - * g_mount_operation_get_is_tcrypt_system_volume: - * @op: a #GMountOperation. - * - * Check to see whether the mount operation is being used - * for a TCRYPT system volume. - * - * Returns: %TRUE if mount operation is for system volume. - * Since: 2.58 - */ - - -/** - * g_mount_operation_get_password: - * @op: a #GMountOperation. - * - * Gets a password from the mount operation. - * - * Returns: (nullable): a string containing the password within @op. - */ - - -/** - * g_mount_operation_get_password_save: - * @op: a #GMountOperation. - * - * Gets the state of saving passwords for the mount operation. - * - * Returns: a #GPasswordSave flag. - */ - - -/** - * g_mount_operation_get_pim: - * @op: a #GMountOperation. - * - * Gets a PIM from the mount operation. - * - * Returns: The VeraCrypt PIM within @op. - * Since: 2.58 - */ - - -/** - * g_mount_operation_get_username: - * @op: a #GMountOperation. - * - * Get the user name from the mount operation. - * - * Returns: (nullable): a string containing the user name. - */ - - -/** - * g_mount_operation_new: - * - * Creates a new mount operation. - * - * Returns: a #GMountOperation. - */ - - -/** - * g_mount_operation_reply: - * @op: a #GMountOperation - * @result: a #GMountOperationResult - * - * Emits the #GMountOperation::reply signal. - */ - - -/** - * g_mount_operation_set_anonymous: - * @op: a #GMountOperation. - * @anonymous: boolean value. - * - * Sets the mount operation to use an anonymous user if @anonymous is %TRUE. - */ - - -/** - * g_mount_operation_set_choice: - * @op: a #GMountOperation. - * @choice: an integer. - * - * Sets a default choice for the mount operation. - */ - - -/** - * g_mount_operation_set_domain: - * @op: a #GMountOperation. - * @domain: (nullable): the domain to set. - * - * Sets the mount operation's domain. - */ - - -/** - * g_mount_operation_set_is_tcrypt_hidden_volume: - * @op: a #GMountOperation. - * @hidden_volume: boolean value. - * - * Sets the mount operation to use a hidden volume if @hidden_volume is %TRUE. - * - * Since: 2.58 - */ - - -/** - * g_mount_operation_set_is_tcrypt_system_volume: - * @op: a #GMountOperation. - * @system_volume: boolean value. - * - * Sets the mount operation to use a system volume if @system_volume is %TRUE. - * - * Since: 2.58 - */ - - -/** - * g_mount_operation_set_password: - * @op: a #GMountOperation. - * @password: (nullable): password to set. - * - * Sets the mount operation's password to @password. - */ - - -/** - * g_mount_operation_set_password_save: - * @op: a #GMountOperation. - * @save: a set of #GPasswordSave flags. - * - * Sets the state of saving passwords for the mount operation. - */ - - -/** - * g_mount_operation_set_pim: - * @op: a #GMountOperation. - * @pim: an unsigned integer. - * - * Sets the mount operation's PIM to @pim. - * - * Since: 2.58 - */ - - -/** - * g_mount_operation_set_username: - * @op: a #GMountOperation. - * @username: (nullable): input username. - * - * Sets the user name within @op to @username. - */ - - -/** - * g_mount_remount: - * @mount: a #GMount. - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. - * - * Remounts a mount. This is an asynchronous operation, and is - * finished by calling g_mount_remount_finish() with the @mount - * and #GAsyncResults data returned in the @callback. - * - * Remounting is useful when some setting affecting the operation - * of the volume has been changed, as these may need a remount to - * take affect. While this is semantically equivalent with unmounting - * and then remounting not all backends might need to actually be - * unmounted. - */ - - -/** - * g_mount_remount_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes remounting a mount. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. - * - * Returns: %TRUE if the mount was successfully remounted. %FALSE otherwise. - */ - - -/** - * g_mount_shadow: - * @mount: A #GMount. - * - * Increments the shadow count on @mount. Usually used by - * #GVolumeMonitor implementations when creating a shadow mount for - * @mount, see g_mount_is_shadowed() for more information. The caller - * will need to emit the #GMount::changed signal on @mount manually. - * - * Since: 2.20 - */ - - -/** - * g_mount_unmount: - * @mount: a #GMount. - * @flags: flags affecting the operation - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. - * - * Unmounts a mount. This is an asynchronous operation, and is - * finished by calling g_mount_unmount_finish() with the @mount - * and #GAsyncResult data returned in the @callback. - * - * Deprecated: 2.22: Use g_mount_unmount_with_operation() instead. - */ - - -/** - * g_mount_unmount_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes unmounting a mount. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. - * - * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise. - * Deprecated: 2.22: Use g_mount_unmount_with_operation_finish() instead. - */ - - -/** - * g_mount_unmount_with_operation: - * @mount: a #GMount. - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid - * user interaction. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. - * - * Unmounts a mount. This is an asynchronous operation, and is - * finished by calling g_mount_unmount_with_operation_finish() with the @mount - * and #GAsyncResult data returned in the @callback. - * - * Since: 2.22 - */ - - -/** - * g_mount_unmount_with_operation_finish: - * @mount: a #GMount. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes unmounting a mount. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. - * - * Returns: %TRUE if the mount was successfully unmounted. %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_mount_unshadow: - * @mount: A #GMount. - * - * Decrements the shadow count on @mount. Usually used by - * #GVolumeMonitor implementations when destroying a shadow mount for - * @mount, see g_mount_is_shadowed() for more information. The caller - * will need to emit the #GMount::changed signal on @mount manually. - * - * Since: 2.20 - */ - - -/** - * g_native_socket_address_new: - * @native: a native address object - * @len: the length of @native, in bytes - * - * Creates a new #GNativeSocketAddress for @native and @len. - * - * Returns: a new #GNativeSocketAddress - * Since: 2.46 - */ - - -/** - * g_network_address_get_hostname: - * @addr: a #GNetworkAddress - * - * Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, - * depending on what @addr was created with. - * - * Returns: @addr's hostname - * Since: 2.22 - */ - - -/** - * g_network_address_get_port: - * @addr: a #GNetworkAddress - * - * Gets @addr's port number - * - * Returns: @addr's port (which may be 0) - * Since: 2.22 - */ - - -/** - * g_network_address_get_scheme: - * @addr: a #GNetworkAddress - * - * Gets @addr's scheme - * - * Returns: (nullable): @addr's scheme (%NULL if not built from URI) - * Since: 2.26 - */ - - -/** - * g_network_address_new: - * @hostname: the hostname - * @port: the port - * - * Creates a new #GSocketConnectable for connecting to the given - * @hostname and @port. - * - * Note that depending on the configuration of the machine, a - * @hostname of `localhost` may refer to the IPv4 loopback address - * only, or to both IPv4 and IPv6; use - * g_network_address_new_loopback() to create a #GNetworkAddress that - * is guaranteed to resolve to both addresses. - * - * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress - * Since: 2.22 - */ - - -/** - * g_network_address_new_loopback: - * @port: the port - * - * Creates a new #GSocketConnectable for connecting to the local host - * over a loopback connection to the given @port. This is intended for - * use in connecting to local services which may be running on IPv4 or - * IPv6. - * - * The connectable will return IPv4 and IPv6 loopback addresses, - * regardless of how the host resolves `localhost`. By contrast, - * g_network_address_new() will often only return an IPv4 address when - * resolving `localhost`, and an IPv6 address for `localhost6`. - * - * g_network_address_get_hostname() will always return `localhost` for - * a #GNetworkAddress created with this constructor. - * - * Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress - * Since: 2.44 - */ - - -/** - * g_network_address_parse: - * @host_and_port: the hostname and optionally a port - * @default_port: the default port if not in @host_and_port - * @error: a pointer to a #GError, or %NULL - * - * Creates a new #GSocketConnectable for connecting to the given - * @hostname and @port. May fail and return %NULL in case - * parsing @host_and_port fails. - * - * @host_and_port may be in any of a number of recognised formats; an IPv6 - * address, an IPv4 address, or a domain name (in which case a DNS - * lookup is performed). Quoting with [] is supported for all address - * types. A port override may be specified in the usual way with a - * colon. - * - * If no port is specified in @host_and_port then @default_port will be - * used as the port number to connect to. - * - * In general, @host_and_port is expected to be provided by the user - * (allowing them to give the hostname, and a port override if necessary) - * and @default_port is expected to be provided by the application. - * - * (The port component of @host_and_port can also be specified as a - * service name rather than as a numeric port, but this functionality - * is deprecated, because it depends on the contents of /etc/services, - * which is generally quite sparse on platforms other than Linux.) - * - * Returns: (transfer full) (type GNetworkAddress): the new - * #GNetworkAddress, or %NULL on error - * Since: 2.22 - */ - - -/** - * g_network_address_parse_uri: - * @uri: the hostname and optionally a port - * @default_port: The default port if none is found in the URI - * @error: a pointer to a #GError, or %NULL - * - * Creates a new #GSocketConnectable for connecting to the given - * @uri. May fail and return %NULL in case parsing @uri fails. - * - * Using this rather than g_network_address_new() or - * g_network_address_parse() allows #GSocketClient to determine - * when to use application-specific proxy protocols. - * - * Returns: (transfer full) (type GNetworkAddress): the new - * #GNetworkAddress, or %NULL on error - * Since: 2.26 - */ - - -/** - * g_network_monitor_base_add_network: - * @monitor: the #GNetworkMonitorBase - * @network: (transfer none): a #GInetAddressMask - * - * Adds @network to @monitor's list of available networks. - * - * Since: 2.32 - */ - - -/** - * g_network_monitor_base_remove_network: - * @monitor: the #GNetworkMonitorBase - * @network: a #GInetAddressMask - * - * Removes @network from @monitor's list of available networks. - * - * Since: 2.32 - */ - - -/** - * g_network_monitor_base_set_networks: - * @monitor: the #GNetworkMonitorBase - * @networks: (array length=length): an array of #GInetAddressMask - * @length: length of @networks - * - * Drops @monitor's current list of available networks and replaces - * it with @networks. - */ - - -/** - * g_network_monitor_can_reach: - * @monitor: a #GNetworkMonitor - * @connectable: a #GSocketConnectable - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL - * - * Attempts to determine whether or not the host pointed to by - * @connectable can be reached, without actually trying to connect to - * it. - * - * This may return %TRUE even when #GNetworkMonitor:network-available - * is %FALSE, if, for example, @monitor can determine that - * @connectable refers to a host on a local network. - * - * If @monitor believes that an attempt to connect to @connectable - * will succeed, it will return %TRUE. Otherwise, it will return - * %FALSE and set @error to an appropriate error (such as - * %G_IO_ERROR_HOST_UNREACHABLE). - * - * Note that although this does not attempt to connect to - * @connectable, it may still block for a brief period of time (eg, - * trying to do multicast DNS on the local network), so if you do not - * want to block, you should use g_network_monitor_can_reach_async(). - * - * Returns: %TRUE if @connectable is reachable, %FALSE if not. - * Since: 2.32 - */ - - -/** - * g_network_monitor_can_reach_async: - * @monitor: a #GNetworkMonitor - * @connectable: a #GSocketConnectable - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback to call when the - * request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Asynchronously attempts to determine whether or not the host - * pointed to by @connectable can be reached, without actually - * trying to connect to it. - * - * For more details, see g_network_monitor_can_reach(). - * - * When the operation is finished, @callback will be called. - * You can then call g_network_monitor_can_reach_finish() - * to get the result of the operation. - */ - - -/** - * g_network_monitor_can_reach_finish: - * @monitor: a #GNetworkMonitor - * @result: a #GAsyncResult - * @error: return location for errors, or %NULL - * - * Finishes an async network connectivity test. - * See g_network_monitor_can_reach_async(). - * - * Returns: %TRUE if network is reachable, %FALSE if not. - */ - - -/** - * g_network_monitor_get_connectivity: - * @monitor: the #GNetworkMonitor - * - * Gets a more detailed networking state than - * g_network_monitor_get_network_available(). - * - * If #GNetworkMonitor:network-available is %FALSE, then the - * connectivity state will be %G_NETWORK_CONNECTIVITY_LOCAL. - * - * If #GNetworkMonitor:network-available is %TRUE, then the - * connectivity state will be %G_NETWORK_CONNECTIVITY_FULL (if there - * is full Internet connectivity), %G_NETWORK_CONNECTIVITY_LIMITED (if - * the host has a default route, but appears to be unable to actually - * reach the full Internet), or %G_NETWORK_CONNECTIVITY_PORTAL (if the - * host is trapped behind a "captive portal" that requires some sort - * of login or acknowledgement before allowing full Internet access). - * - * Note that in the case of %G_NETWORK_CONNECTIVITY_LIMITED and - * %G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are - * reachable but others are not. In this case, applications can - * attempt to connect to remote servers, but should gracefully fall - * back to their "offline" behavior if the connection attempt fails. - * - * Returns: the network connectivity state - * Since: 2.44 - */ - - -/** - * g_network_monitor_get_default: - * - * Gets the default #GNetworkMonitor for the system. - * - * Returns: (not nullable) (transfer none): a #GNetworkMonitor, which will be - * a dummy object if no network monitor is available - * Since: 2.32 - */ - - -/** - * g_network_monitor_get_network_available: - * @monitor: the #GNetworkMonitor - * - * Checks if the network is available. "Available" here means that the - * system has a default route available for at least one of IPv4 or - * IPv6. It does not necessarily imply that the public Internet is - * reachable. See #GNetworkMonitor:network-available for more details. - * - * Returns: whether the network is available - * Since: 2.32 - */ - - -/** - * g_network_monitor_get_network_metered: - * @monitor: the #GNetworkMonitor - * - * Checks if the network is metered. - * See #GNetworkMonitor:network-metered for more details. - * - * Returns: whether the connection is metered - * Since: 2.46 - */ - - -/** - * g_network_service_get_domain: - * @srv: a #GNetworkService - * - * Gets the domain that @srv serves. This might be either UTF-8 or - * ASCII-encoded, depending on what @srv was created with. - * - * Returns: @srv's domain name - * Since: 2.22 - */ - - -/** - * g_network_service_get_protocol: - * @srv: a #GNetworkService - * - * Gets @srv's protocol name (eg, "tcp"). - * - * Returns: @srv's protocol name - * Since: 2.22 - */ - - -/** - * g_network_service_get_scheme: - * @srv: a #GNetworkService - * - * Gets the URI scheme used to resolve proxies. By default, the service name - * is used as scheme. - * - * Returns: @srv's scheme name - * Since: 2.26 - */ - - -/** - * g_network_service_get_service: - * @srv: a #GNetworkService - * - * Gets @srv's service name (eg, "ldap"). - * - * Returns: @srv's service name - * Since: 2.22 - */ - - -/** - * g_network_service_new: - * @service: the service type to look up (eg, "ldap") - * @protocol: the networking protocol to use for @service (eg, "tcp") - * @domain: the DNS domain to look up the service in - * - * Creates a new #GNetworkService representing the given @service, - * @protocol, and @domain. This will initially be unresolved; use the - * #GSocketConnectable interface to resolve it. - * - * Returns: (transfer full) (type GNetworkService): a new #GNetworkService - * Since: 2.22 - */ - - -/** - * g_network_service_set_scheme: - * @srv: a #GNetworkService - * @scheme: a URI scheme - * - * Set's the URI scheme used to resolve proxies. By default, the service name - * is used as scheme. - * - * Since: 2.26 - */ - - -/** - * 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_notification_add_button: - * @notification: a #GNotification - * @label: label of the button - * @detailed_action: a detailed action name - * - * Adds a button to @notification that activates the action in - * @detailed_action when clicked. That action must be an - * application-wide action (starting with "app."). If @detailed_action - * contains a target, the action will be activated with that target as - * its parameter. - * - * See g_action_parse_detailed_name() for a description of the format - * for @detailed_action. - * - * Since: 2.40 - */ - - -/** - * g_notification_add_button_with_target: (skip) - * @notification: a #GNotification - * @label: label of the button - * @action: an action name - * @target_format: (nullable): a #GVariant format string, or %NULL - * @...: positional parameters, as determined by @target_format - * - * Adds a button to @notification that activates @action when clicked. - * @action must be an application-wide action (it must start with "app."). - * - * If @target_format is given, it is used to collect remaining - * positional parameters into a #GVariant instance, similar to - * g_variant_new(). @action will be activated with that #GVariant as its - * parameter. - * - * Since: 2.40 - */ - - -/** - * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target) - * @notification: a #GNotification - * @label: label of the button - * @action: an action name - * @target: (nullable): a #GVariant to use as @action's parameter, or %NULL - * - * Adds a button to @notification that activates @action when clicked. - * @action must be an application-wide action (it must start with "app."). - * - * If @target is non-%NULL, @action will be activated with @target as - * its parameter. - * - * Since: 2.40 - */ - - -/** - * g_notification_new: - * @title: the title of the notification - * - * Creates a new #GNotification with @title as its title. - * - * After populating @notification with more details, it can be sent to - * the desktop shell with g_application_send_notification(). Changing - * any properties after this call will not have any effect until - * resending @notification. - * - * Returns: a new #GNotification instance - * Since: 2.40 - */ - - -/** - * g_notification_set_body: - * @notification: a #GNotification - * @body: (nullable): the new body for @notification, or %NULL - * - * Sets the body of @notification to @body. - * - * Since: 2.40 - */ - - -/** - * g_notification_set_category: - * @notification: a #GNotification - * @category: (nullable): the category for @notification, or %NULL for no category - * - * Sets the type of @notification to @category. Categories have a main - * type like `email`, `im` or `device` and can have a detail separated - * by a `.`, e.g. `im.received` or `email.arrived`. Setting the category - * helps the notification server to select proper feedback to the user. - * - * Standard categories are [listed in the specification](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html). - * - * Since: 2.70 - */ - - -/** - * g_notification_set_default_action: - * @notification: a #GNotification - * @detailed_action: a detailed action name - * - * Sets the default action of @notification to @detailed_action. This - * action is activated when the notification is clicked on. - * - * The action in @detailed_action must be an application-wide action (it - * must start with "app."). If @detailed_action contains a target, the - * given action will be activated with that target as its parameter. - * See g_action_parse_detailed_name() for a description of the format - * for @detailed_action. - * - * When no default action is set, the application that the notification - * was sent on is activated. - * - * Since: 2.40 - */ - - -/** - * g_notification_set_default_action_and_target: (skip) - * @notification: a #GNotification - * @action: an action name - * @target_format: (nullable): a #GVariant format string, or %NULL - * @...: positional parameters, as determined by @target_format - * - * Sets the default action of @notification to @action. This action is - * activated when the notification is clicked on. It must be an - * application-wide action (it must start with "app."). - * - * If @target_format is given, it is used to collect remaining - * positional parameters into a #GVariant instance, similar to - * g_variant_new(). @action will be activated with that #GVariant as its - * parameter. - * - * When no default action is set, the application that the notification - * was sent on is activated. - * - * Since: 2.40 - */ - - -/** - * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target) - * @notification: a #GNotification - * @action: an action name - * @target: (nullable): a #GVariant to use as @action's parameter, or %NULL - * - * Sets the default action of @notification to @action. This action is - * activated when the notification is clicked on. It must be an - * application-wide action (start with "app."). - * - * If @target is non-%NULL, @action will be activated with @target as - * its parameter. - * - * When no default action is set, the application that the notification - * was sent on is activated. - * - * Since: 2.40 - */ - - -/** - * g_notification_set_icon: - * @notification: a #GNotification - * @icon: the icon to be shown in @notification, as a #GIcon - * - * Sets the icon of @notification to @icon. - * - * Since: 2.40 - */ - - -/** - * g_notification_set_priority: - * @notification: a #GNotification - * @priority: a #GNotificationPriority - * - * Sets the priority of @notification to @priority. See - * #GNotificationPriority for possible values. - */ - - -/** - * g_notification_set_title: - * @notification: a #GNotification - * @title: the new title for @notification - * - * Sets the title of @notification to @title. - * - * Since: 2.40 - */ - - -/** - * g_notification_set_urgent: - * @notification: a #GNotification - * @urgent: %TRUE if @notification is urgent - * - * Deprecated in favor of g_notification_set_priority(). - * - * Since: 2.40 - * Deprecated: 2.42: Since 2.42, this has been deprecated in favour of - * g_notification_set_priority(). - */ - - -/** - * g_null_settings_backend_new: - * - * Creates a readonly #GSettingsBackend. - * - * This backend does not allow changes to settings, so all settings - * will always have their default values. - * - * Returns: (transfer full): a newly created #GSettingsBackend - * Since: 2.28 - */ - - -/** - * g_output_stream_clear_pending: - * @stream: output stream - * - * Clears the pending flag on @stream. - */ - - -/** - * g_output_stream_close: - * @stream: A #GOutputStream. - * @cancellable: (nullable): optional cancellable object - * @error: location to store the error occurring, or %NULL to ignore - * - * Closes the stream, releasing resources related to it. - * - * Once the stream is closed, all other operations will return %G_IO_ERROR_CLOSED. - * Closing a stream multiple times will not return an error. - * - * Closing a stream will automatically flush any outstanding buffers in the - * stream. - * - * Streams will be automatically closed when the last reference - * is dropped, but you might want to call this function to make sure - * resources are released as early as possible. - * - * Some streams might keep the backing store of the stream (e.g. a file descriptor) - * open after the stream is closed. See the documentation for the individual - * stream for details. - * - * On failure the first error that happened will be reported, but the close - * operation will finish as much as possible. A stream that failed to - * close will still return %G_IO_ERROR_CLOSED for all operations. Still, it - * is important to check and report the error to the user, otherwise - * there might be a loss of data as all data might not be written. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * Cancelling a close will still leave the stream closed, but there some streams - * can use a faster close that doesn't block to e.g. check errors. On - * cancellation (as with any error) there is no guarantee that all written - * data will reach the target. - * - * Returns: %TRUE on success, %FALSE on failure - */ - - -/** - * g_output_stream_close_async: - * @stream: A #GOutputStream. - * @io_priority: the io priority of the request. - * @cancellable: (nullable): optional cancellable object - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Requests an asynchronous close of the stream, releasing resources - * related to it. When the operation is finished @callback will be - * called. You can then call g_output_stream_close_finish() to get - * the result of the operation. - * - * For behaviour details see g_output_stream_close(). - * - * The asynchronous methods have a default fallback that uses threads - * to implement asynchronicity, so they are optional for inheriting - * classes. However, if you override one you must override all. - */ - - -/** - * g_output_stream_close_finish: - * @stream: a #GOutputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Closes an output stream. - * - * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. - */ - - -/** - * g_output_stream_flush: - * @stream: a #GOutputStream. - * @cancellable: (nullable): optional cancellable object - * @error: location to store the error occurring, or %NULL to ignore - * - * Forces a write of all user-space buffered data for the given - * @stream. Will block during the operation. Closing the stream will - * implicitly cause a flush. - * - * This function is optional for inherited classes. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE on success, %FALSE on error - */ - - -/** - * g_output_stream_flush_async: - * @stream: a #GOutputStream. - * @io_priority: the io priority of the request. - * @cancellable: (nullable): 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 - * - * Forces an asynchronous write of all user-space buffered data for - * the given @stream. - * For behaviour details see g_output_stream_flush(). - * - * When the operation is finished @callback will be - * called. You can then call g_output_stream_flush_finish() to get the - * result of the operation. - */ - - -/** - * g_output_stream_flush_finish: - * @stream: a #GOutputStream. - * @result: a GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes flushing an output stream. - * - * Returns: %TRUE if flush operation succeeded, %FALSE otherwise. - */ - - -/** - * g_output_stream_has_pending: - * @stream: a #GOutputStream. - * - * Checks if an output stream has pending actions. - * - * Returns: %TRUE if @stream has pending actions. - */ - - -/** - * g_output_stream_is_closed: - * @stream: a #GOutputStream. - * - * Checks if an output stream has already been closed. - * - * Returns: %TRUE if @stream is closed. %FALSE otherwise. - */ - - -/** - * g_output_stream_is_closing: - * @stream: a #GOutputStream. - * - * Checks if an output stream is being closed. This can be - * used inside e.g. a flush implementation to see if the - * flush (or other i/o operation) is called from within - * the closing operation. - * - * Returns: %TRUE if @stream is being closed. %FALSE otherwise. - * Since: 2.24 - */ - - -/** - * g_output_stream_printf: - * @stream: a #GOutputStream. - * @bytes_written: (out) (optional): location to store the number of bytes that was - * written to the stream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * @format: the format string. See the printf() documentation - * @...: the parameters to insert into the format string - * - * This is a utility function around g_output_stream_write_all(). It - * uses g_strdup_vprintf() to turn @format and @... into a string that - * is then written to @stream. - * - * See the documentation of g_output_stream_write_all() about the - * behavior of the actual write operation. - * - * Note that partial writes cannot be properly checked with this - * function due to the variable length of the written string, if you - * need precise control over partial write failures, you need to - * create you own printf()-like wrapper around g_output_stream_write() - * or g_output_stream_write_all(). - * - * Since: 2.40 - * Returns: %TRUE on success, %FALSE if there was an error - */ - - -/** - * g_output_stream_set_pending: - * @stream: a #GOutputStream. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Sets @stream to have actions pending. If the pending flag is - * already set or @stream is closed, it will return %FALSE and set - * @error. - * - * Returns: %TRUE if pending was previously unset and is now set. - */ - - -/** - * g_output_stream_splice: - * @stream: a #GOutputStream. - * @source: a #GInputStream. - * @flags: a set of #GOutputStreamSpliceFlags. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Splices an input stream into an output stream. - * - * Returns: a #gssize containing the size of the data spliced, or - * -1 if an error occurred. Note that if the number of bytes - * spliced is greater than %G_MAXSSIZE, then that will be - * returned, and there is no way to determine the actual number - * of bytes spliced. - */ - - -/** - * g_output_stream_splice_async: - * @stream: a #GOutputStream. - * @source: a #GInputStream. - * @flags: a set of #GOutputStreamSpliceFlags. - * @io_priority: the io priority of the request. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. - * - * Splices a stream asynchronously. - * When the operation is finished @callback will be called. - * You can then call g_output_stream_splice_finish() to get the - * result of the operation. - * - * For the synchronous, blocking version of this function, see - * g_output_stream_splice(). - */ - - -/** - * g_output_stream_splice_finish: - * @stream: a #GOutputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes an asynchronous stream splice operation. - * - * Returns: a #gssize of the number of bytes spliced. Note that if the - * number of bytes spliced is greater than %G_MAXSSIZE, then that - * will be returned, and there is no way to determine the actual - * number of bytes spliced. - */ - - -/** - * g_output_stream_vprintf: - * @stream: a #GOutputStream. - * @bytes_written: (out) (optional): location to store the number of bytes that was - * written to the stream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * @format: the format string. See the printf() documentation - * @args: the parameters to insert into the format string - * - * This is a utility function around g_output_stream_write_all(). It - * uses g_strdup_vprintf() to turn @format and @args into a string that - * is then written to @stream. - * - * See the documentation of g_output_stream_write_all() about the - * behavior of the actual write operation. - * - * Note that partial writes cannot be properly checked with this - * function due to the variable length of the written string, if you - * need precise control over partial write failures, you need to - * create you own printf()-like wrapper around g_output_stream_write() - * or g_output_stream_write_all(). - * - * Since: 2.40 - * Returns: %TRUE on success, %FALSE if there was an error - */ - - -/** - * g_output_stream_write: (virtual write_fn) - * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. - * @count: the number of bytes to write - * @cancellable: (nullable): optional cancellable object - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to write @count bytes from @buffer into the stream. Will block - * during the operation. - * - * If count is 0, returns 0 and does nothing. A value of @count - * larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the number of bytes written to the stream is returned. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. on a partial I/O error, or if there is not enough - * storage in the stream. All writes block until at least one byte - * is written or an error occurs; 0 is never returned (unless - * @count is 0). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * - * On error -1 is returned and @error is set accordingly. - * - * Returns: Number of bytes written, or -1 on error - */ - - -/** - * g_output_stream_write_all: - * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. - * @count: the number of bytes to write - * @bytes_written: (out) (optional): location to store the number of bytes that was - * written to the stream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to write @count bytes from @buffer into the stream. Will block - * during the operation. - * - * This function is similar to g_output_stream_write(), except it tries to - * write as many bytes as requested, only stopping on an error. - * - * On a successful write of @count bytes, %TRUE is returned, and @bytes_written - * is set to @count. - * - * If there is an error during the operation %FALSE is returned and @error - * is set to indicate the error status. - * - * As a special exception to the normal conventions for functions that - * use #GError, if this function returns %FALSE (and sets @error) then - * @bytes_written will be set to the number of bytes that were - * successfully written before the error was encountered. This - * functionality is only available from C. If you need it from another - * language then you must write your own loop around - * g_output_stream_write(). - * - * Returns: %TRUE on success, %FALSE if there was an error - */ - - -/** - * g_output_stream_write_all_async: - * @stream: A #GOutputStream - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write - * @count: the number of bytes to write - * @io_priority: the io priority of the request - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Request an asynchronous write of @count bytes from @buffer into - * the stream. When the operation is finished @callback will be called. - * You can then call g_output_stream_write_all_finish() to get the result of the - * operation. - * - * This is the asynchronous version of g_output_stream_write_all(). - * - * Call g_output_stream_write_all_finish() to collect the result. - * - * Any outstanding I/O request with higher priority (lower numerical - * value) will be executed before an outstanding request with lower - * priority. Default priority is %G_PRIORITY_DEFAULT. - * - * Note that no copy of @buffer will be made, so it must stay valid - * until @callback is called. - * - * Since: 2.44 - */ - - -/** - * g_output_stream_write_all_finish: - * @stream: a #GOutputStream - * @result: a #GAsyncResult - * @bytes_written: (out) (optional): location to store the number of bytes that was written to the stream - * @error: a #GError location to store the error occurring, or %NULL to ignore. - * - * Finishes an asynchronous stream write operation started with - * g_output_stream_write_all_async(). - * - * As a special exception to the normal conventions for functions that - * use #GError, if this function returns %FALSE (and sets @error) then - * @bytes_written will be set to the number of bytes that were - * successfully written before the error was encountered. This - * functionality is only available from C. If you need it from another - * language then you must write your own loop around - * g_output_stream_write_async(). - * - * Returns: %TRUE on success, %FALSE if there was an error - * Since: 2.44 - */ - - -/** - * g_output_stream_write_async: - * @stream: A #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. - * @count: the number of bytes to write - * @io_priority: the io priority of the request. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Request an asynchronous write of @count bytes from @buffer into - * the stream. When the operation is finished @callback will be called. - * You can then call g_output_stream_write_finish() to get the result of the - * operation. - * - * During an async request no other sync and async calls are allowed, - * and will result in %G_IO_ERROR_PENDING errors. - * - * A value of @count larger than %G_MAXSSIZE will cause a - * %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the number of bytes written will be passed to the - * @callback. It is not an error if this is not the same as the - * requested size, as it can happen e.g. on a partial I/O error, - * but generally we try to write as many bytes as requested. - * - * You are guaranteed that this method will never fail with - * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the - * method will just wait until this changes. - * - * Any outstanding I/O request with higher priority (lower numerical - * value) will be executed before an outstanding request with lower - * priority. Default priority is %G_PRIORITY_DEFAULT. - * - * The asynchronous methods have a default fallback that uses threads - * to implement asynchronicity, so they are optional for inheriting - * classes. However, if you override one you must override all. - * - * For the synchronous, blocking version of this function, see - * g_output_stream_write(). - * - * Note that no copy of @buffer will be made, so it must stay valid - * until @callback is called. See g_output_stream_write_bytes_async() - * for a #GBytes version that will automatically hold a reference to - * the contents (without copying) for the duration of the call. - */ - - -/** - * g_output_stream_write_bytes: - * @stream: a #GOutputStream. - * @bytes: the #GBytes to write - * @cancellable: (nullable): optional cancellable object - * @error: location to store the error occurring, or %NULL to ignore - * - * A wrapper function for g_output_stream_write() which takes a - * #GBytes as input. This can be more convenient for use by language - * bindings or in other cases where the refcounted nature of #GBytes - * is helpful over a bare pointer interface. - * - * However, note that this function may still perform partial writes, - * just like g_output_stream_write(). If that occurs, to continue - * writing, you will need to create a new #GBytes containing just the - * remaining bytes, using g_bytes_new_from_bytes(). Passing the same - * #GBytes instance multiple times potentially can result in duplicated - * data in the output stream. - * - * Returns: Number of bytes written, or -1 on error - */ - - -/** - * g_output_stream_write_bytes_async: - * @stream: A #GOutputStream. - * @bytes: The bytes to write - * @io_priority: the io priority of the request. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * This function is similar to g_output_stream_write_async(), but - * takes a #GBytes as input. Due to the refcounted nature of #GBytes, - * this allows the stream to avoid taking a copy of the data. - * - * However, note that this function may still perform partial writes, - * just like g_output_stream_write_async(). If that occurs, to continue - * writing, you will need to create a new #GBytes containing just the - * remaining bytes, using g_bytes_new_from_bytes(). Passing the same - * #GBytes instance multiple times potentially can result in duplicated - * data in the output stream. - * - * For the synchronous, blocking version of this function, see - * g_output_stream_write_bytes(). - */ - - -/** - * g_output_stream_write_bytes_finish: - * @stream: a #GOutputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes a stream write-from-#GBytes operation. - * - * Returns: a #gssize containing the number of bytes written to the stream. - */ - - -/** - * g_output_stream_write_finish: - * @stream: a #GOutputStream. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes a stream write operation. - * - * Returns: a #gssize containing the number of bytes written to the stream. - */ - - -/** - * g_output_stream_writev: (virtual writev_fn) - * @stream: a #GOutputStream. - * @vectors: (array length=n_vectors): the buffer containing the #GOutputVectors to write. - * @n_vectors: the number of vectors to write - * @bytes_written: (out) (optional): location to store the number of bytes that were - * written to the stream - * @cancellable: (nullable): optional cancellable object - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to write the bytes contained in the @n_vectors @vectors into the - * stream. Will block during the operation. - * - * If @n_vectors is 0 or the sum of all bytes in @vectors is 0, returns 0 and - * does nothing. - * - * On success, the number of bytes written to the stream is returned. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. on a partial I/O error, or if there is not enough - * storage in the stream. All writes block until at least one byte - * is written or an error occurs; 0 is never returned (unless - * @n_vectors is 0 or the sum of all bytes in @vectors is 0). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * - * Some implementations of g_output_stream_writev() may have limitations on the - * aggregate buffer size, and will return %G_IO_ERROR_INVALID_ARGUMENT if these - * are exceeded. For example, when writing to a local file on UNIX platforms, - * the aggregate buffer size must not exceed %G_MAXSSIZE bytes. - * - * Returns: %TRUE on success, %FALSE if there was an error - * Since: 2.60 - */ - - -/** - * g_output_stream_writev_all: - * @stream: a #GOutputStream. - * @vectors: (array length=n_vectors): the buffer containing the #GOutputVectors to write. - * @n_vectors: the number of vectors to write - * @bytes_written: (out) (optional): location to store the number of bytes that were - * written to the stream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to write the bytes contained in the @n_vectors @vectors into the - * stream. Will block during the operation. - * - * This function is similar to g_output_stream_writev(), except it tries to - * write as many bytes as requested, only stopping on an error. - * - * On a successful write of all @n_vectors vectors, %TRUE is returned, and - * @bytes_written is set to the sum of all the sizes of @vectors. - * - * If there is an error during the operation %FALSE is returned and @error - * is set to indicate the error status. - * - * As a special exception to the normal conventions for functions that - * use #GError, if this function returns %FALSE (and sets @error) then - * @bytes_written will be set to the number of bytes that were - * successfully written before the error was encountered. This - * functionality is only available from C. If you need it from another - * language then you must write your own loop around - * g_output_stream_write(). - * - * The content of the individual elements of @vectors might be changed by this - * function. - * - * Returns: %TRUE on success, %FALSE if there was an error - * Since: 2.60 - */ - - -/** - * g_output_stream_writev_all_async: - * @stream: A #GOutputStream - * @vectors: (array length=n_vectors): the buffer containing the #GOutputVectors to write. - * @n_vectors: the number of vectors to write - * @io_priority: the I/O priority of the request - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Request an asynchronous write of the bytes contained in the @n_vectors @vectors into - * the stream. When the operation is finished @callback will be called. - * You can then call g_output_stream_writev_all_finish() to get the result of the - * operation. - * - * This is the asynchronous version of g_output_stream_writev_all(). - * - * Call g_output_stream_writev_all_finish() to collect the result. - * - * Any outstanding I/O request with higher priority (lower numerical - * value) will be executed before an outstanding request with lower - * priority. Default priority is %G_PRIORITY_DEFAULT. - * - * Note that no copy of @vectors will be made, so it must stay valid - * until @callback is called. The content of the individual elements - * of @vectors might be changed by this function. - * - * Since: 2.60 - */ - - -/** - * g_output_stream_writev_all_finish: - * @stream: a #GOutputStream - * @result: a #GAsyncResult - * @bytes_written: (out) (optional): location to store the number of bytes that were written to the stream - * @error: a #GError location to store the error occurring, or %NULL to ignore. - * - * Finishes an asynchronous stream write operation started with - * g_output_stream_writev_all_async(). - * - * As a special exception to the normal conventions for functions that - * use #GError, if this function returns %FALSE (and sets @error) then - * @bytes_written will be set to the number of bytes that were - * successfully written before the error was encountered. This - * functionality is only available from C. If you need it from another - * language then you must write your own loop around - * g_output_stream_writev_async(). - * - * Returns: %TRUE on success, %FALSE if there was an error - * Since: 2.60 - */ - - -/** - * g_output_stream_writev_async: - * @stream: A #GOutputStream. - * @vectors: (array length=n_vectors): the buffer containing the #GOutputVectors to write. - * @n_vectors: the number of vectors to write - * @io_priority: the I/O priority of the request. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): callback to call when the request is satisfied - * @user_data: (closure): the data to pass to callback function - * - * Request an asynchronous write of the bytes contained in @n_vectors @vectors into - * the stream. When the operation is finished @callback will be called. - * You can then call g_output_stream_writev_finish() to get the result of the - * operation. - * - * During an async request no other sync and async calls are allowed, - * and will result in %G_IO_ERROR_PENDING errors. - * - * On success, the number of bytes written will be passed to the - * @callback. It is not an error if this is not the same as the - * requested size, as it can happen e.g. on a partial I/O error, - * but generally we try to write as many bytes as requested. - * - * You are guaranteed that this method will never fail with - * %G_IO_ERROR_WOULD_BLOCK — if @stream can't accept more data, the - * method will just wait until this changes. - * - * Any outstanding I/O request with higher priority (lower numerical - * value) will be executed before an outstanding request with lower - * priority. Default priority is %G_PRIORITY_DEFAULT. - * - * The asynchronous methods have a default fallback that uses threads - * to implement asynchronicity, so they are optional for inheriting - * classes. However, if you override one you must override all. - * - * For the synchronous, blocking version of this function, see - * g_output_stream_writev(). - * - * Note that no copy of @vectors will be made, so it must stay valid - * until @callback is called. - * - * Since: 2.60 - */ - - -/** - * g_output_stream_writev_finish: - * @stream: a #GOutputStream. - * @result: a #GAsyncResult. - * @bytes_written: (out) (optional): location to store the number of bytes that were written to the stream - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes a stream writev operation. - * - * Returns: %TRUE on success, %FALSE if there was an error - * Since: 2.60 - */ - - -/** - * g_permission_acquire: - * @permission: a #GPermission instance - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a pointer to a %NULL #GError, or %NULL - * - * Attempts to acquire the permission represented by @permission. - * - * The precise method by which this happens depends on the permission - * and the underlying authentication mechanism. A simple example is - * that a dialog may appear asking the user to enter their password. - * - * You should check with g_permission_get_can_acquire() before calling - * this function. - * - * If the permission is acquired then %TRUE is returned. Otherwise, - * %FALSE is returned and @error is set appropriately. - * - * This call is blocking, likely for a very long time (in the case that - * user interaction is required). See g_permission_acquire_async() for - * the non-blocking version. - * - * Returns: %TRUE if the permission was successfully acquired - * Since: 2.26 - */ - - -/** - * g_permission_acquire_async: - * @permission: a #GPermission instance - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback to call when done - * @user_data: the user data to pass to @callback - * - * Attempts to acquire the permission represented by @permission. - * - * This is the first half of the asynchronous version of - * g_permission_acquire(). - * - * Since: 2.26 - */ - - -/** - * g_permission_acquire_finish: - * @permission: a #GPermission instance - * @result: the #GAsyncResult given to the #GAsyncReadyCallback - * @error: a pointer to a %NULL #GError, or %NULL - * - * Collects the result of attempting to acquire the permission - * represented by @permission. - * - * This is the second half of the asynchronous version of - * g_permission_acquire(). - * - * Returns: %TRUE if the permission was successfully acquired - * Since: 2.26 - */ - - -/** - * g_permission_get_allowed: - * @permission: a #GPermission instance - * - * Gets the value of the 'allowed' property. This property is %TRUE if - * the caller currently has permission to perform the action that - * @permission represents the permission to perform. - * - * Returns: the value of the 'allowed' property - * Since: 2.26 - */ - - -/** - * g_permission_get_can_acquire: - * @permission: a #GPermission instance - * - * Gets the value of the 'can-acquire' property. This property is %TRUE - * if it is generally possible to acquire the permission by calling - * g_permission_acquire(). - * - * Returns: the value of the 'can-acquire' property - * Since: 2.26 - */ - - -/** - * g_permission_get_can_release: - * @permission: a #GPermission instance - * - * Gets the value of the 'can-release' property. This property is %TRUE - * if it is generally possible to release the permission by calling - * g_permission_release(). - * - * Returns: the value of the 'can-release' property - * Since: 2.26 - */ - - -/** - * g_permission_impl_update: - * @permission: a #GPermission instance - * @allowed: the new value for the 'allowed' property - * @can_acquire: the new value for the 'can-acquire' property - * @can_release: the new value for the 'can-release' property - * - * This function is called by the #GPermission implementation to update - * the properties of the permission. You should never call this - * function except from a #GPermission implementation. - * - * GObject notify signals are generated, as appropriate. - * - * Since: 2.26 - */ - - -/** - * g_permission_release: - * @permission: a #GPermission instance - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a pointer to a %NULL #GError, or %NULL - * - * Attempts to release the permission represented by @permission. - * - * The precise method by which this happens depends on the permission - * and the underlying authentication mechanism. In most cases the - * permission will be dropped immediately without further action. - * - * You should check with g_permission_get_can_release() before calling - * this function. - * - * If the permission is released then %TRUE is returned. Otherwise, - * %FALSE is returned and @error is set appropriately. - * - * This call is blocking, likely for a very long time (in the case that - * user interaction is required). See g_permission_release_async() for - * the non-blocking version. - * - * Returns: %TRUE if the permission was successfully released - * Since: 2.26 - */ - - -/** - * g_permission_release_async: - * @permission: a #GPermission instance - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: the #GAsyncReadyCallback to call when done - * @user_data: the user data to pass to @callback - * - * Attempts to release the permission represented by @permission. - * - * This is the first half of the asynchronous version of - * g_permission_release(). - * - * Since: 2.26 - */ - - -/** - * g_permission_release_finish: - * @permission: a #GPermission instance - * @result: the #GAsyncResult given to the #GAsyncReadyCallback - * @error: a pointer to a %NULL #GError, or %NULL - * - * Collects the result of attempting to release the permission - * represented by @permission. - * - * This is the second half of the asynchronous version of - * g_permission_release(). - * - * Returns: %TRUE if the permission was successfully released - * Since: 2.26 - */ - - -/** - * g_pollable_input_stream_can_poll: - * @stream: a #GPollableInputStream. - * - * Checks if @stream is actually pollable. Some classes may implement - * #GPollableInputStream but have only certain instances of that class - * be pollable. If this method returns %FALSE, then the behavior of - * other #GPollableInputStream methods is undefined. - * - * For any given stream, the value returned by this method is constant; - * a stream cannot switch from pollable to non-pollable or vice versa. - * - * Returns: %TRUE if @stream is pollable, %FALSE if not. - * Since: 2.28 - */ - - -/** - * g_pollable_input_stream_create_source: - * @stream: a #GPollableInputStream. - * @cancellable: (nullable): a #GCancellable, or %NULL - * - * Creates a #GSource that triggers when @stream can be read, or - * @cancellable is triggered or an error occurs. The callback on the - * source is of the #GPollableSourceFunc type. - * - * As with g_pollable_input_stream_is_readable(), it is possible that - * the stream may not actually be readable even after the source - * triggers, so you should use g_pollable_input_stream_read_nonblocking() - * rather than g_input_stream_read() from the callback. - * - * Returns: (transfer full): a new #GSource - * Since: 2.28 - */ - - -/** - * g_pollable_input_stream_is_readable: - * @stream: a #GPollableInputStream. - * - * Checks if @stream can be read. - * - * Note that some stream types may not be able to implement this 100% - * reliably, and it is possible that a call to g_input_stream_read() - * after this returns %TRUE would still block. To guarantee - * non-blocking behavior, you should always use - * g_pollable_input_stream_read_nonblocking(), which will return a - * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. - * - * Returns: %TRUE if @stream is readable, %FALSE if not. If an error - * has occurred on @stream, this will result in - * g_pollable_input_stream_is_readable() returning %TRUE, and the - * next attempt to read will return the error. - * Since: 2.28 - */ - - -/** - * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking) - * @stream: a #GPollableInputStream - * @buffer: (array length=count) (element-type guint8) (out caller-allocates): a - * buffer to read data into (which should be at least @count bytes long). - * @count: (in): the number of bytes you want to read - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Attempts to read up to @count bytes from @stream into @buffer, as - * with g_input_stream_read(). If @stream is not currently readable, - * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can - * use g_pollable_input_stream_create_source() to create a #GSource - * that will be triggered when @stream is readable. - * - * Note that since this method never blocks, you cannot actually - * use @cancellable to cancel it. However, it will return an error - * if @cancellable has already been cancelled when you call, which - * may happen if you call this method after a source triggers due - * to having been cancelled. - * - * Returns: the number of bytes read, or -1 on error (including - * %G_IO_ERROR_WOULD_BLOCK). - */ - - -/** - * g_pollable_output_stream_can_poll: - * @stream: a #GPollableOutputStream. - * - * Checks if @stream is actually pollable. Some classes may implement - * #GPollableOutputStream but have only certain instances of that - * class be pollable. If this method returns %FALSE, then the behavior - * of other #GPollableOutputStream methods is undefined. - * - * For any given stream, the value returned by this method is constant; - * a stream cannot switch from pollable to non-pollable or vice versa. - * - * Returns: %TRUE if @stream is pollable, %FALSE if not. - * Since: 2.28 - */ - - -/** - * g_pollable_output_stream_create_source: - * @stream: a #GPollableOutputStream. - * @cancellable: (nullable): a #GCancellable, or %NULL - * - * Creates a #GSource that triggers when @stream can be written, or - * @cancellable is triggered or an error occurs. The callback on the - * source is of the #GPollableSourceFunc type. - * - * As with g_pollable_output_stream_is_writable(), it is possible that - * the stream may not actually be writable even after the source - * triggers, so you should use g_pollable_output_stream_write_nonblocking() - * rather than g_output_stream_write() from the callback. - * - * Returns: (transfer full): a new #GSource - * Since: 2.28 - */ - - -/** - * g_pollable_output_stream_is_writable: - * @stream: a #GPollableOutputStream. - * - * Checks if @stream can be written. - * - * Note that some stream types may not be able to implement this 100% - * reliably, and it is possible that a call to g_output_stream_write() - * after this returns %TRUE would still block. To guarantee - * non-blocking behavior, you should always use - * g_pollable_output_stream_write_nonblocking(), which will return a - * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. - * - * Returns: %TRUE if @stream is writable, %FALSE if not. If an error - * has occurred on @stream, this will result in - * g_pollable_output_stream_is_writable() returning %TRUE, and the - * next attempt to write will return the error. - * Since: 2.28 - */ - - -/** - * g_pollable_output_stream_write_nonblocking: (virtual write_nonblocking) - * @stream: a #GPollableOutputStream - * @buffer: (array length=count) (element-type guint8): a buffer to write - * data from - * @count: the number of bytes you want to write - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Attempts to write up to @count bytes from @buffer to @stream, as - * with g_output_stream_write(). If @stream is not currently writable, - * this will immediately return %G_IO_ERROR_WOULD_BLOCK, and you can - * use g_pollable_output_stream_create_source() to create a #GSource - * that will be triggered when @stream is writable. - * - * Note that since this method never blocks, you cannot actually - * use @cancellable to cancel it. However, it will return an error - * if @cancellable has already been cancelled when you call, which - * may happen if you call this method after a source triggers due - * to having been cancelled. - * - * Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying - * transports like D/TLS require that you re-send the same @buffer and - * @count in the next write call. - * - * Returns: the number of bytes written, or -1 on error (including - * %G_IO_ERROR_WOULD_BLOCK). - */ - - -/** - * g_pollable_output_stream_writev_nonblocking: (virtual writev_nonblocking) - * @stream: a #GPollableOutputStream - * @vectors: (array length=n_vectors): the buffer containing the #GOutputVectors to write. - * @n_vectors: the number of vectors to write - * @bytes_written: (out) (optional): location to store the number of bytes that were - * written to the stream - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Attempts to write the bytes contained in the @n_vectors @vectors to @stream, - * as with g_output_stream_writev(). If @stream is not currently writable, - * this will immediately return %@G_POLLABLE_RETURN_WOULD_BLOCK, and you can - * use g_pollable_output_stream_create_source() to create a #GSource - * that will be triggered when @stream is writable. @error will *not* be - * set in that case. - * - * Note that since this method never blocks, you cannot actually - * use @cancellable to cancel it. However, it will return an error - * if @cancellable has already been cancelled when you call, which - * may happen if you call this method after a source triggers due - * to having been cancelled. - * - * Also note that if %G_POLLABLE_RETURN_WOULD_BLOCK is returned some underlying - * transports like D/TLS require that you re-send the same @vectors and - * @n_vectors in the next write call. - * - * Returns: %@G_POLLABLE_RETURN_OK on success, %G_POLLABLE_RETURN_WOULD_BLOCK - * if the stream is not currently writable (and @error is *not* set), or - * %G_POLLABLE_RETURN_FAILED if there was an error in which case @error will - * be set. - * Since: 2.60 - */ - - -/** - * g_pollable_source_new: - * @pollable_stream: the stream associated with the new source - * - * Utility method for #GPollableInputStream and #GPollableOutputStream - * implementations. Creates a new #GSource that expects a callback of - * type #GPollableSourceFunc. The new source does not actually do - * anything on its own; use g_source_add_child_source() to add other - * sources to it to cause it to trigger. - * - * Returns: (transfer full): the new #GSource. - * Since: 2.28 - */ - - -/** - * g_pollable_source_new_full: - * @pollable_stream: (type GObject): the stream associated with the - * new source - * @child_source: (nullable): optional child source to attach - * @cancellable: (nullable): optional #GCancellable to attach - * - * Utility method for #GPollableInputStream and #GPollableOutputStream - * implementations. Creates a new #GSource, as with - * g_pollable_source_new(), but also attaching @child_source (with a - * dummy callback), and @cancellable, if they are non-%NULL. - * - * Returns: (transfer full): the new #GSource. - * Since: 2.34 - */ - - -/** - * g_pollable_stream_read: - * @stream: a #GInputStream - * @buffer: (array length=count) (element-type guint8): a buffer to - * read data into - * @count: the number of bytes to read - * @blocking: whether to do blocking I/O - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to read from @stream, as with g_input_stream_read() (if - * @blocking is %TRUE) or g_pollable_input_stream_read_nonblocking() - * (if @blocking is %FALSE). This can be used to more easily share - * code between blocking and non-blocking implementations of a method. - * - * If @blocking is %FALSE, then @stream must be a - * #GPollableInputStream for which g_pollable_input_stream_can_poll() - * returns %TRUE, or else the behavior is undefined. If @blocking is - * %TRUE, then @stream does not need to be a #GPollableInputStream. - * - * Returns: the number of bytes read, or -1 on error. - * Since: 2.34 - */ - - -/** - * g_pollable_stream_write: - * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer - * containing the data to write. - * @count: the number of bytes to write - * @blocking: whether to do blocking I/O - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to write to @stream, as with g_output_stream_write() (if - * @blocking is %TRUE) or g_pollable_output_stream_write_nonblocking() - * (if @blocking is %FALSE). This can be used to more easily share - * code between blocking and non-blocking implementations of a method. - * - * If @blocking is %FALSE, then @stream must be a - * #GPollableOutputStream for which - * g_pollable_output_stream_can_poll() returns %TRUE or else the - * behavior is undefined. If @blocking is %TRUE, then @stream does not - * need to be a #GPollableOutputStream. - * - * Returns: the number of bytes written, or -1 on error. - * Since: 2.34 - */ - - -/** - * g_pollable_stream_write_all: - * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer - * containing the data to write. - * @count: the number of bytes to write - * @blocking: whether to do blocking I/O - * @bytes_written: (out): location to store the number of bytes that was - * written to the stream - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: location to store the error occurring, or %NULL to ignore - * - * Tries to write @count bytes to @stream, as with - * g_output_stream_write_all(), but using g_pollable_stream_write() - * rather than g_output_stream_write(). - * - * On a successful write of @count bytes, %TRUE is returned, and - * @bytes_written is set to @count. - * - * If there is an error during the operation (including - * %G_IO_ERROR_WOULD_BLOCK in the non-blocking case), %FALSE is - * returned and @error is set to indicate the error status, - * @bytes_written is updated to contain the number of bytes written - * into the stream before the error occurred. - * - * As with g_pollable_stream_write(), if @blocking is %FALSE, then - * @stream must be a #GPollableOutputStream for which - * g_pollable_output_stream_can_poll() returns %TRUE or else the - * behavior is undefined. If @blocking is %TRUE, then @stream does not - * need to be a #GPollableOutputStream. - * - * Returns: %TRUE on success, %FALSE if there was an error - * Since: 2.34 - */ - - -/** - * g_power_profile_monitor_dup_default: - * - * Gets a reference to the default #GPowerProfileMonitor for the system. - * - * Returns: (not nullable) (transfer full): a new reference to the default #GPowerProfileMonitor - * Since: 2.70 - */ - - -/** - * g_power_profile_monitor_get_power_saver_enabled: - * @monitor: a #GPowerProfileMonitor - * - * Gets whether the system is in “Power Saver” mode. - * - * You are expected to listen to the - * #GPowerProfileMonitor::notify::power-saver-enabled signal to know when the profile has - * changed. - * - * Returns: Whether the system is in “Power Saver” mode. - * Since: 2.70 - */ - - -/** - * g_property_action_new: - * @name: the name of the action to create - * @object: (type GObject.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 - * - * Gets @proxy's destination hostname; that is, the name of the host - * that will be connected to via the proxy, not the name of the proxy - * itself. - * - * Returns: the @proxy's destination hostname - * Since: 2.26 - */ - - -/** - * g_proxy_address_get_destination_port: - * @proxy: a #GProxyAddress - * - * Gets @proxy's destination port; that is, the port on the - * destination host that will be connected to via the proxy, not the - * port number of the proxy itself. - * - * Returns: the @proxy's destination port - * Since: 2.26 - */ - - -/** - * g_proxy_address_get_destination_protocol: - * @proxy: a #GProxyAddress - * - * Gets the protocol that is being spoken to the destination - * server; eg, "http" or "ftp". - * - * Returns: the @proxy's destination protocol - * Since: 2.34 - */ - - -/** - * g_proxy_address_get_password: - * @proxy: a #GProxyAddress - * - * Gets @proxy's password. - * - * Returns: (nullable): the @proxy's password - * Since: 2.26 - */ - - -/** - * g_proxy_address_get_protocol: - * @proxy: a #GProxyAddress - * - * Gets @proxy's protocol. eg, "socks" or "http" - * - * Returns: the @proxy's protocol - * Since: 2.26 - */ - - -/** - * g_proxy_address_get_uri: - * @proxy: a #GProxyAddress - * - * Gets the proxy URI that @proxy was constructed from. - * - * Returns: (nullable): the @proxy's URI, or %NULL if unknown - * Since: 2.34 - */ - - -/** - * g_proxy_address_get_username: - * @proxy: a #GProxyAddress - * - * Gets @proxy's username. - * - * Returns: (nullable): the @proxy's username - * Since: 2.26 - */ - - -/** - * g_proxy_address_new: - * @inetaddr: The proxy server #GInetAddress. - * @port: The proxy server port. - * @protocol: The proxy protocol to support, in lower case (e.g. socks, http). - * @dest_hostname: The destination hostname the proxy should tunnel to. - * @dest_port: The destination port to tunnel to. - * @username: (nullable): The username to authenticate to the proxy server - * (or %NULL). - * @password: (nullable): The password to authenticate to the proxy server - * (or %NULL). - * - * Creates a new #GProxyAddress for @inetaddr with @protocol that should - * tunnel through @dest_hostname and @dest_port. - * - * (Note that this method doesn't set the #GProxyAddress:uri or - * #GProxyAddress:destination-protocol fields; use g_object_new() - * directly if you want to set those.) - * - * Returns: a new #GProxyAddress - * Since: 2.26 - */ - - -/** - * g_proxy_connect: - * @proxy: a #GProxy - * @connection: a #GIOStream - * @proxy_address: a #GProxyAddress - * @cancellable: (nullable): a #GCancellable - * @error: return #GError - * - * Given @connection to communicate with a proxy (eg, a - * #GSocketConnection that is connected to the proxy server), this - * does the necessary handshake to connect to @proxy_address, and if - * required, wraps the #GIOStream to handle proxy payload. - * - * Returns: (transfer full): a #GIOStream that will replace @connection. This might - * be the same as @connection, in which case a reference - * will be added. - * Since: 2.26 - */ - - -/** - * g_proxy_connect_async: - * @proxy: a #GProxy - * @connection: a #GIOStream - * @proxy_address: a #GProxyAddress - * @cancellable: (nullable): a #GCancellable - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): callback data - * - * Asynchronous version of g_proxy_connect(). - * - * Since: 2.26 - */ - - -/** - * g_proxy_connect_finish: - * @proxy: a #GProxy - * @result: a #GAsyncResult - * @error: return #GError - * - * See g_proxy_connect(). - * - * Returns: (transfer full): a #GIOStream. - * Since: 2.26 - */ - - -/** - * g_proxy_get_default_for_protocol: - * @protocol: the proxy protocol name (e.g. http, socks, etc) - * - * Find the `gio-proxy` extension point for a proxy implementation that supports - * the specified protocol. - * - * Returns: (nullable) (transfer full): return a #GProxy or NULL if protocol - * is not supported. - * Since: 2.26 - */ - - -/** - * g_proxy_resolver_get_default: - * - * Gets the default #GProxyResolver for the system. - * - * Returns: (not nullable) (transfer none): the default #GProxyResolver, which - * will be a dummy object if no proxy resolver is available - * Since: 2.26 - */ - - -/** - * g_proxy_resolver_is_supported: - * @resolver: a #GProxyResolver - * - * Checks if @resolver can be used on this system. (This is used - * internally; g_proxy_resolver_get_default() will only return a proxy - * resolver that returns %TRUE for this method.) - * - * Returns: %TRUE if @resolver is supported. - * Since: 2.26 - */ - - -/** - * g_proxy_resolver_lookup: - * @resolver: a #GProxyResolver - * @uri: a URI representing the destination to connect to - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL - * - * Looks into the system proxy configuration to determine what proxy, - * if any, to use to connect to @uri. The returned proxy URIs are of - * the form `://[user[:password]@]host:port` or - * `direct://`, where could be http, rtsp, socks - * or other proxying protocol. - * - * If you don't know what network protocol is being used on the - * socket, you should use `none` as the URI protocol. - * In this case, the resolver might still return a generic proxy type - * (such as SOCKS), but would not return protocol-specific proxy types - * (such as http). - * - * `direct://` is used when no proxy is needed. - * Direct connection should not be attempted unless it is part of the - * returned array of proxies. - * - * Returns: (transfer full) (array zero-terminated=1): A - * NULL-terminated array of proxy URIs. Must be freed - * with g_strfreev(). - * Since: 2.26 - */ - - -/** - * g_proxy_resolver_lookup_async: - * @resolver: a #GProxyResolver - * @uri: a URI representing the destination to connect to - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback - * - * Asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more - * details. - * - * Since: 2.26 - */ - - -/** - * g_proxy_resolver_lookup_finish: - * @resolver: a #GProxyResolver - * @result: the result passed to your #GAsyncReadyCallback - * @error: return location for a #GError, or %NULL - * - * Call this function to obtain the array of proxy URIs when - * g_proxy_resolver_lookup_async() is complete. See - * g_proxy_resolver_lookup() for more details. - * - * Returns: (transfer full) (array zero-terminated=1): A - * NULL-terminated array of proxy URIs. Must be freed - * with g_strfreev(). - * Since: 2.26 - */ - - -/** - * g_proxy_supports_hostname: - * @proxy: a #GProxy - * - * Some proxy protocols expect to be passed a hostname, which they - * will resolve to an IP address themselves. Others, like SOCKS4, do - * not allow this. This function will return %FALSE if @proxy is - * implementing such a protocol. When %FALSE is returned, the caller - * should resolve the destination hostname first, and then pass a - * #GProxyAddress containing the stringified IP address to - * g_proxy_connect() or g_proxy_connect_async(). - * - * Returns: %TRUE if hostname resolution is supported. - * Since: 2.26 - */ - - -/** - * g_remote_action_group_activate_action_full: - * @remote: a #GDBusActionGroup - * @action_name: the name of the action to activate - * @parameter: (nullable): the optional parameter to the activation - * @platform_data: the platform data to send - * - * Activates the remote action. - * - * This is the same as g_action_group_activate_action() except that it - * allows for provision of "platform data" to be sent along with the - * activation request. This typically contains details such as the user - * interaction timestamp or startup notification information. - * - * @platform_data must be non-%NULL and must have the type - * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. - * - * Since: 2.32 - */ - - -/** - * g_remote_action_group_change_action_state_full: - * @remote: a #GRemoteActionGroup - * @action_name: the name of the action to change the state of - * @value: the new requested value for the state - * @platform_data: the platform data to send - * - * Changes the state of a remote action. - * - * This is the same as g_action_group_change_action_state() except that - * it allows for provision of "platform data" to be sent along with the - * state change request. This typically contains details such as the - * user interaction timestamp or startup notification information. - * - * @platform_data must be non-%NULL and must have the type - * %G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed. - * - * Since: 2.32 - */ - - -/** - * g_resolver_error_quark: - * - * Gets the #GResolver Error Quark. - * - * Returns: a #GQuark. - * Since: 2.22 - */ - - -/** - * g_resolver_free_addresses: (skip) - * @addresses: a #GList of #GInetAddress - * - * Frees @addresses (which should be the return value from - * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()). - * (This is a convenience method; you can also simply free the results - * by hand.) - * - * Since: 2.22 - */ - - -/** - * g_resolver_free_targets: (skip) - * @targets: a #GList of #GSrvTarget - * - * Frees @targets (which should be the return value from - * g_resolver_lookup_service() or g_resolver_lookup_service_finish()). - * (This is a convenience method; you can also simply free the - * results by hand.) - * - * Since: 2.22 - */ - - -/** - * g_resolver_get_default: - * - * Gets the default #GResolver. You should unref it when you are done - * with it. #GResolver may use its reference count as a hint about how - * many threads it should allocate for concurrent DNS resolutions. - * - * Returns: (transfer full): the default #GResolver. - * Since: 2.22 - */ - - -/** - * g_resolver_lookup_by_address: - * @resolver: a #GResolver - * @address: the address to reverse-resolve - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL - * - * Synchronously reverse-resolves @address to determine its - * associated hostname. - * - * If the DNS resolution fails, @error (if non-%NULL) will be set to - * a value from #GResolverError. - * - * If @cancellable is non-%NULL, it can be used to cancel the - * operation, in which case @error (if non-%NULL) will be set to - * %G_IO_ERROR_CANCELLED. - * - * Returns: a hostname (either ASCII-only, or in ASCII-encoded - * form), or %NULL on error. - * Since: 2.22 - */ - - -/** - * g_resolver_lookup_by_address_async: - * @resolver: a #GResolver - * @address: the address to reverse-resolve - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback - * - * Begins asynchronously reverse-resolving @address to determine its - * associated hostname, and eventually calls @callback, which must - * call g_resolver_lookup_by_address_finish() to get the final result. - * - * Since: 2.22 - */ - - -/** - * g_resolver_lookup_by_address_finish: - * @resolver: a #GResolver - * @result: the result passed to your #GAsyncReadyCallback - * @error: return location for a #GError, or %NULL - * - * Retrieves the result of a previous call to - * g_resolver_lookup_by_address_async(). - * - * If the DNS resolution failed, @error (if non-%NULL) will be set to - * a value from #GResolverError. If the operation was cancelled, - * @error will be set to %G_IO_ERROR_CANCELLED. - * - * Returns: a hostname (either ASCII-only, or in ASCII-encoded - * form), or %NULL on error. - * Since: 2.22 - */ - - -/** - * g_resolver_lookup_by_name: - * @resolver: a #GResolver - * @hostname: the hostname to look up - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL - * - * Synchronously resolves @hostname to determine its associated IP - * address(es). @hostname may be an ASCII-only or UTF-8 hostname, or - * the textual form of an IP address (in which case this just becomes - * a wrapper around g_inet_address_new_from_string()). - * - * On success, g_resolver_lookup_by_name() will return a non-empty #GList of - * #GInetAddress, sorted in order of preference and guaranteed to not - * contain duplicates. That is, if using the result to connect to - * @hostname, you should attempt to connect to the first address - * first, then the second if the first fails, etc. If you are using - * the result to listen on a socket, it is appropriate to add each - * result using e.g. g_socket_listener_add_address(). - * - * If the DNS resolution fails, @error (if non-%NULL) will be set to a - * value from #GResolverError and %NULL will be returned. - * - * If @cancellable is non-%NULL, it can be used to cancel the - * operation, in which case @error (if non-%NULL) will be set to - * %G_IO_ERROR_CANCELLED. - * - * If you are planning to connect to a socket on the resolved IP - * address, it may be easier to create a #GNetworkAddress and use its - * #GSocketConnectable interface. - * - * Returns: (element-type GInetAddress) (transfer full): a non-empty #GList - * of #GInetAddress, or %NULL on error. You - * must unref each of the addresses and free the list when you are - * done with it. (You can use g_resolver_free_addresses() to do this.) - * Since: 2.22 - */ - - -/** - * g_resolver_lookup_by_name_async: - * @resolver: a #GResolver - * @hostname: the hostname to look up the address of - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback - * - * Begins asynchronously resolving @hostname to determine its - * associated IP address(es), and eventually calls @callback, which - * must call g_resolver_lookup_by_name_finish() to get the result. - * See g_resolver_lookup_by_name() for more details. - * - * Since: 2.22 - */ - - -/** - * g_resolver_lookup_by_name_finish: - * @resolver: a #GResolver - * @result: the result passed to your #GAsyncReadyCallback - * @error: return location for a #GError, or %NULL - * - * Retrieves the result of a call to - * g_resolver_lookup_by_name_async(). - * - * If the DNS resolution failed, @error (if non-%NULL) will be set to - * a value from #GResolverError. If the operation was cancelled, - * @error will be set to %G_IO_ERROR_CANCELLED. - * - * Returns: (element-type GInetAddress) (transfer full): a #GList - * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() - * for more details. - * Since: 2.22 - */ - - -/** - * g_resolver_lookup_by_name_with_flags: - * @resolver: a #GResolver - * @hostname: the hostname to look up - * @flags: extra #GResolverNameLookupFlags for the lookup - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: (nullable): return location for a #GError, or %NULL - * - * This differs from g_resolver_lookup_by_name() in that you can modify - * the lookup behavior with @flags. For example this can be used to limit - * results with #G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY. - * - * Returns: (element-type GInetAddress) (transfer full): a non-empty #GList - * of #GInetAddress, or %NULL on error. You - * must unref each of the addresses and free the list when you are - * done with it. (You can use g_resolver_free_addresses() to do this.) - * Since: 2.60 - */ - - -/** - * g_resolver_lookup_by_name_with_flags_async: - * @resolver: a #GResolver - * @hostname: the hostname to look up the address of - * @flags: extra #GResolverNameLookupFlags for the lookup - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback - * - * Begins asynchronously resolving @hostname to determine its - * associated IP address(es), and eventually calls @callback, which - * must call g_resolver_lookup_by_name_with_flags_finish() to get the result. - * See g_resolver_lookup_by_name() for more details. - * - * Since: 2.60 - */ - - -/** - * g_resolver_lookup_by_name_with_flags_finish: - * @resolver: a #GResolver - * @result: the result passed to your #GAsyncReadyCallback - * @error: return location for a #GError, or %NULL - * - * Retrieves the result of a call to - * g_resolver_lookup_by_name_with_flags_async(). - * - * If the DNS resolution failed, @error (if non-%NULL) will be set to - * a value from #GResolverError. If the operation was cancelled, - * @error will be set to %G_IO_ERROR_CANCELLED. - * - * Returns: (element-type GInetAddress) (transfer full): a #GList - * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() - * for more details. - * Since: 2.60 - */ - - -/** - * g_resolver_lookup_records: - * @resolver: a #GResolver - * @rrname: the DNS name to look up the record for - * @record_type: the type of DNS record to look up - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL - * - * Synchronously performs a DNS record lookup for the given @rrname and returns - * a list of records as #GVariant tuples. See #GResolverRecordType for - * information on what the records contain for each @record_type. - * - * If the DNS resolution fails, @error (if non-%NULL) will be set to - * a value from #GResolverError and %NULL will be returned. - * - * If @cancellable is non-%NULL, it can be used to cancel the - * operation, in which case @error (if non-%NULL) will be set to - * %G_IO_ERROR_CANCELLED. - * - * Returns: (element-type GVariant) (transfer full): a non-empty #GList of - * #GVariant, or %NULL on error. You must free each of the records and the list - * when you are done with it. (You can use g_list_free_full() with - * g_variant_unref() to do this.) - * Since: 2.34 - */ - - -/** - * g_resolver_lookup_records_async: - * @resolver: a #GResolver - * @rrname: the DNS name to look up the record for - * @record_type: the type of DNS record to look up - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback - * - * Begins asynchronously performing a DNS lookup for the given - * @rrname, and eventually calls @callback, which must call - * g_resolver_lookup_records_finish() to get the final result. See - * g_resolver_lookup_records() for more details. - * - * Since: 2.34 - */ - - -/** - * g_resolver_lookup_records_finish: - * @resolver: a #GResolver - * @result: the result passed to your #GAsyncReadyCallback - * @error: return location for a #GError, or %NULL - * - * Retrieves the result of a previous call to - * g_resolver_lookup_records_async(). Returns a non-empty list of records as - * #GVariant tuples. See #GResolverRecordType for information on what the - * records contain. - * - * If the DNS resolution failed, @error (if non-%NULL) will be set to - * a value from #GResolverError. If the operation was cancelled, - * @error will be set to %G_IO_ERROR_CANCELLED. - * - * Returns: (element-type GVariant) (transfer full): a non-empty #GList of - * #GVariant, or %NULL on error. You must free each of the records and the list - * when you are done with it. (You can use g_list_free_full() with - * g_variant_unref() to do this.) - * Since: 2.34 - */ - - -/** - * g_resolver_lookup_service: - * @resolver: a #GResolver - * @service: the service type to look up (eg, "ldap") - * @protocol: the networking protocol to use for @service (eg, "tcp") - * @domain: the DNS domain to look up the service in - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: return location for a #GError, or %NULL - * - * Synchronously performs a DNS SRV lookup for the given @service and - * @protocol in the given @domain and returns an array of #GSrvTarget. - * @domain may be an ASCII-only or UTF-8 hostname. Note also that the - * @service and @protocol arguments do not include the leading underscore - * that appears in the actual DNS entry. - * - * On success, g_resolver_lookup_service() will return a non-empty #GList of - * #GSrvTarget, sorted in order of preference. (That is, you should - * attempt to connect to the first target first, then the second if - * the first fails, etc.) - * - * If the DNS resolution fails, @error (if non-%NULL) will be set to - * a value from #GResolverError and %NULL will be returned. - * - * If @cancellable is non-%NULL, it can be used to cancel the - * operation, in which case @error (if non-%NULL) will be set to - * %G_IO_ERROR_CANCELLED. - * - * If you are planning to connect to the service, it is usually easier - * to create a #GNetworkService and use its #GSocketConnectable - * interface. - * - * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of - * #GSrvTarget, or %NULL on error. You must free each of the targets and the - * list when you are done with it. (You can use g_resolver_free_targets() to do - * this.) - * Since: 2.22 - */ - - -/** - * g_resolver_lookup_service_async: - * @resolver: a #GResolver - * @service: the service type to look up (eg, "ldap") - * @protocol: the networking protocol to use for @service (eg, "tcp") - * @domain: the DNS domain to look up the service in - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): callback to call after resolution completes - * @user_data: (closure): data for @callback - * - * Begins asynchronously performing a DNS SRV lookup for the given - * @service and @protocol in the given @domain, and eventually calls - * @callback, which must call g_resolver_lookup_service_finish() to - * get the final result. See g_resolver_lookup_service() for more - * details. - * - * Since: 2.22 - */ - - -/** - * g_resolver_lookup_service_finish: - * @resolver: a #GResolver - * @result: the result passed to your #GAsyncReadyCallback - * @error: return location for a #GError, or %NULL - * - * Retrieves the result of a previous call to - * g_resolver_lookup_service_async(). - * - * If the DNS resolution failed, @error (if non-%NULL) will be set to - * a value from #GResolverError. If the operation was cancelled, - * @error will be set to %G_IO_ERROR_CANCELLED. - * - * Returns: (element-type GSrvTarget) (transfer full): a non-empty #GList of - * #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more - * details. - * Since: 2.22 - */ - - -/** - * g_resolver_set_default: - * @resolver: the new default #GResolver - * - * Sets @resolver to be the application's default resolver (reffing - * @resolver, and unreffing the previous default resolver, if any). - * Future calls to g_resolver_get_default() will return this resolver. - * - * This can be used if an application wants to perform any sort of DNS - * caching or "pinning"; it can implement its own #GResolver that - * calls the original default resolver for DNS operations, and - * implements its own cache policies on top of that, and then set - * itself as the default resolver for all later code to use. - * - * Since: 2.22 - */ - - -/** - * g_resource_enumerate_children: - * @resource: A #GResource - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @error: return location for a #GError, or %NULL - * - * Returns all the names of children at the specified @path in the resource. - * The return result is a %NULL terminated list of strings which should - * be released with g_strfreev(). - * - * If @path is invalid or does not exist in the #GResource, - * %G_RESOURCE_ERROR_NOT_FOUND will be returned. - * - * @lookup_flags controls the behaviour of the lookup. - * - * Returns: (array zero-terminated=1) (transfer full): an array of constant strings - * Since: 2.32 - */ - - -/** - * g_resource_error_quark: - * - * Gets the #GResource Error Quark. - * - * Returns: a #GQuark - * Since: 2.32 - */ - - -/** - * g_resource_get_info: - * @resource: A #GResource - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @size: (out) (optional): a location to place the length of the contents of the file, - * or %NULL if the length is not needed - * @flags: (out) (optional): a location to place the flags about the file, - * or %NULL if the length is not needed - * @error: return location for a #GError, or %NULL - * - * Looks for a file at the specified @path in the resource and - * if found returns information about it. - * - * @lookup_flags controls the behaviour of the lookup. - * - * Returns: %TRUE if the file was found. %FALSE if there were errors - * Since: 2.32 - */ - - -/** - * g_resource_load: - * @filename: (type filename): the path of a filename to load, in the GLib filename encoding - * @error: return location for a #GError, or %NULL - * - * Loads a binary resource bundle and creates a #GResource representation of it, allowing - * you to query it for data. - * - * If you want to use this resource in the global resource namespace you need - * to register it with g_resources_register(). - * - * If @filename is empty or the data in it is corrupt, - * %G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or - * there is an error in reading it, an error from g_mapped_file_new() will be - * returned. - * - * Returns: (transfer full): a new #GResource, or %NULL on error - * Since: 2.32 - */ - - -/** - * g_resource_lookup_data: - * @resource: A #GResource - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @error: return location for a #GError, or %NULL - * - * Looks for a file at the specified @path in the resource and - * returns a #GBytes that lets you directly access the data in - * memory. - * - * The data is always followed by a zero byte, so you - * can safely use the data as a C string. However, that byte - * is not included in the size of the GBytes. - * - * For uncompressed resource files this is a pointer directly into - * the resource bundle, which is typically in some readonly data section - * in the program binary. For compressed files we allocate memory on - * the heap and automatically uncompress the data. - * - * @lookup_flags controls the behaviour of the lookup. - * - * Returns: (transfer full): #GBytes or %NULL on error. - * Free the returned object with g_bytes_unref() - * Since: 2.32 - */ - - -/** - * g_resource_new_from_data: - * @data: A #GBytes - * @error: return location for a #GError, or %NULL - * - * Creates a GResource from a reference to the binary resource bundle. - * This will keep a reference to @data while the resource lives, so - * the data should not be modified or freed. - * - * If you want to use this resource in the global resource namespace you need - * to register it with g_resources_register(). - * - * Note: @data must be backed by memory that is at least pointer aligned. - * Otherwise this function will internally create a copy of the memory since - * GLib 2.56, or in older versions fail and exit the process. - * - * If @data is empty or corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. - * - * Returns: (transfer full): a new #GResource, or %NULL on error - * Since: 2.32 - */ - - -/** - * g_resource_open_stream: - * @resource: A #GResource - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @error: return location for a #GError, or %NULL - * - * Looks for a file at the specified @path in the resource and - * returns a #GInputStream that lets you read the data. - * - * @lookup_flags controls the behaviour of the lookup. - * - * Returns: (transfer full): #GInputStream or %NULL on error. - * Free the returned object with g_object_unref() - * Since: 2.32 - */ - - -/** - * g_resource_ref: - * @resource: A #GResource - * - * Atomically increments the reference count of @resource by one. This - * function is MT-safe and may be called from any thread. - * - * Returns: The passed in #GResource - * Since: 2.32 - */ - - -/** - * g_resource_unref: - * @resource: A #GResource - * - * Atomically decrements the reference count of @resource by one. If the - * reference count drops to 0, all memory allocated by the resource is - * released. This function is MT-safe and may be called from any - * thread. - * - * Since: 2.32 - */ - - -/** - * g_resources_enumerate_children: - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @error: return location for a #GError, or %NULL - * - * Returns all the names of children at the specified @path in the set of - * globally registered resources. - * The return result is a %NULL terminated list of strings which should - * be released with g_strfreev(). - * - * @lookup_flags controls the behaviour of the lookup. - * - * Returns: (array zero-terminated=1) (transfer full): an array of constant strings - * Since: 2.32 - */ - - -/** - * g_resources_get_info: - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @size: (out) (optional): a location to place the length of the contents of the file, - * or %NULL if the length is not needed - * @flags: (out) (optional): a location to place the #GResourceFlags about the file, - * or %NULL if the flags are not needed - * @error: return location for a #GError, or %NULL - * - * Looks for a file at the specified @path in the set of - * globally registered resources and if found returns information about it. - * - * @lookup_flags controls the behaviour of the lookup. - * - * Returns: %TRUE if the file was found. %FALSE if there were errors - * Since: 2.32 - */ - - -/** - * g_resources_lookup_data: - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @error: return location for a #GError, or %NULL - * - * Looks for a file at the specified @path in the set of - * globally registered resources and returns a #GBytes that - * lets you directly access the data in memory. - * - * The data is always followed by a zero byte, so you - * can safely use the data as a C string. However, that byte - * is not included in the size of the GBytes. - * - * For uncompressed resource files this is a pointer directly into - * the resource bundle, which is typically in some readonly data section - * in the program binary. For compressed files we allocate memory on - * the heap and automatically uncompress the data. - * - * @lookup_flags controls the behaviour of the lookup. - * - * Returns: (transfer full): #GBytes or %NULL on error. - * Free the returned object with g_bytes_unref() - * Since: 2.32 - */ - - -/** - * g_resources_open_stream: - * @path: A pathname inside the resource - * @lookup_flags: A #GResourceLookupFlags - * @error: return location for a #GError, or %NULL - * - * Looks for a file at the specified @path in the set of - * globally registered resources and returns a #GInputStream - * that lets you read the data. - * - * @lookup_flags controls the behaviour of the lookup. - * - * Returns: (transfer full): #GInputStream or %NULL on error. - * Free the returned object with g_object_unref() - * Since: 2.32 - */ - - -/** - * g_resources_register: - * @resource: A #GResource - * - * Registers the resource with the process-global set of resources. - * Once a resource is registered the files in it can be accessed - * with the global resource lookup functions like g_resources_lookup_data(). - * - * Since: 2.32 - */ - - -/** - * g_resources_unregister: - * @resource: A #GResource - * - * Unregisters the resource from the process-global set of resources. - * - * Since: 2.32 - */ - - -/** - * g_seekable_can_seek: - * @seekable: a #GSeekable. - * - * Tests if the stream supports the #GSeekableIface. - * - * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise. - */ - - -/** - * g_seekable_can_truncate: - * @seekable: a #GSeekable. - * - * Tests if the length of the stream can be adjusted with - * g_seekable_truncate(). - * - * Returns: %TRUE if the stream can be truncated, %FALSE otherwise. - */ - - -/** - * g_seekable_seek: - * @seekable: a #GSeekable. - * @offset: a #goffset. - * @type: a #GSeekType. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Seeks in the stream by the given @offset, modified by @type. - * - * Attempting to seek past the end of the stream will have different - * results depending on if the stream is fixed-sized or resizable. If - * the stream is resizable then seeking past the end and then writing - * will result in zeros filling the empty space. Seeking past the end - * of a resizable stream and reading will result in EOF. Seeking past - * the end of a fixed-sized stream will fail. - * - * Any operation that would result in a negative offset will fail. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: %TRUE if successful. If an error - * has occurred, this function will return %FALSE and set @error - * appropriately if present. - */ - - -/** - * g_seekable_tell: - * @seekable: a #GSeekable. - * - * Tells the current position within the stream. - * - * Returns: the (positive or zero) offset from the beginning of the - * buffer, zero if the target is not seekable. - */ - - -/** - * g_seekable_truncate: (virtual truncate_fn) - * @seekable: a #GSeekable. - * @offset: new length for @seekable, in bytes. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Sets the length of the stream to @offset. If the stream was previously - * larger than @offset, the extra data is discarded. If the stream was - * previously shorter than @offset, it is extended with NUL ('\0') bytes. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * - * Returns: %TRUE if successful. If an error - * has occurred, this function will return %FALSE and set @error - * appropriately if present. - */ - - -/** - * g_settings_apply: - * @settings: a #GSettings instance - * - * Applies any changes that have been made to the settings. This - * function does nothing unless @settings is in 'delay-apply' mode; - * see g_settings_delay(). In the normal case settings are always - * applied immediately. - */ - - -/** - * g_settings_backend_changed: - * @backend: a #GSettingsBackend implementation - * @key: the name of the key - * @origin_tag: the origin tag - * - * Signals that a single key has possibly changed. Backend - * implementations should call this if a key has possibly changed its - * value. - * - * @key must be a valid key (ie starting with a slash, not containing - * '//', and not ending with a slash). - * - * The implementation must call this function during any call to - * g_settings_backend_write(), before the call returns (except in the - * case that no keys are actually changed and it cares to detect this - * fact). It may not rely on the existence of a mainloop for - * dispatching the signal later. - * - * The implementation may call this function at any other time it likes - * in response to other events (such as changes occurring outside of the - * program). These calls may originate from a mainloop or may originate - * in response to any other action (including from calls to - * g_settings_backend_write()). - * - * In the case that this call is in response to a call to - * g_settings_backend_write() then @origin_tag must be set to the same - * value that was passed to that call. - * - * Since: 2.26 - */ - - -/** - * g_settings_backend_changed_tree: - * @backend: a #GSettingsBackend implementation - * @tree: a #GTree containing the changes - * @origin_tag: the origin tag - * - * This call is a convenience wrapper. It gets the list of changes from - * @tree, computes the longest common prefix and calls - * g_settings_backend_changed(). - * - * Since: 2.26 - */ - - -/** - * g_settings_backend_flatten_tree: - * @tree: a #GTree containing the changes - * @path: (out): the location to save the path - * @keys: (out) (transfer container) (array zero-terminated=1): the - * location to save the relative keys - * @values: (out) (optional) (transfer container) (array zero-terminated=1): - * the location to save the values, or %NULL - * - * Calculate the longest common prefix of all keys in a tree and write - * out an array of the key names relative to that prefix and, - * optionally, the value to store at each of those keys. - * - * You must free the value returned in @path, @keys and @values using - * g_free(). You should not attempt to free or unref the contents of - * @keys or @values. - * - * Since: 2.26 - */ - - -/** - * g_settings_backend_get_default: - * - * Returns the default #GSettingsBackend. It is possible to override - * the default by setting the `GSETTINGS_BACKEND` environment variable - * to the name of a settings backend. - * - * The user gets a reference to the backend. - * - * Returns: (not nullable) (transfer full): the default #GSettingsBackend, - * which will be a dummy (memory) settings backend if no other settings - * backend is available. - * Since: 2.28 - */ - - -/** - * g_settings_backend_keys_changed: - * @backend: a #GSettingsBackend implementation - * @path: the path containing the changes - * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys - * @origin_tag: the origin tag - * - * Signals that a list of keys have possibly changed. Backend - * implementations should call this if keys have possibly changed their - * values. - * - * @path must be a valid path (ie starting and ending with a slash and - * not containing '//'). Each string in @items must form a valid key - * name when @path is prefixed to it (ie: each item must not start or - * end with '/' and must not contain '//'). - * - * The meaning of this signal is that any of the key names resulting - * from the contatenation of @path with each item in @items may have - * changed. - * - * The same rules for when notifications must occur apply as per - * g_settings_backend_changed(). These two calls can be used - * interchangeably if exactly one item has changed (although in that - * case g_settings_backend_changed() is definitely preferred). - * - * For efficiency reasons, the implementation should strive for @path to - * be as long as possible (ie: the longest common prefix of all of the - * keys that were changed) but this is not strictly required. - * - * Since: 2.26 - */ - - -/** - * g_settings_backend_path_changed: - * @backend: a #GSettingsBackend implementation - * @path: the path containing the changes - * @origin_tag: the origin tag - * - * Signals that all keys below a given path may have possibly changed. - * Backend implementations should call this if an entire path of keys - * have possibly changed their values. - * - * @path must be a valid path (ie starting and ending with a slash and - * not containing '//'). - * - * The meaning of this signal is that any of the key which has a name - * starting with @path may have changed. - * - * The same rules for when notifications must occur apply as per - * g_settings_backend_changed(). This call might be an appropriate - * reasponse to a 'reset' call but implementations are also free to - * explicitly list the keys that were affected by that call if they can - * easily do so. - * - * For efficiency reasons, the implementation should strive for @path to - * be as long as possible (ie: the longest common prefix of all of the - * keys that were changed) but this is not strictly required. As an - * example, if this function is called with the path of "/" then every - * single key in the application will be notified of a possible change. - * - * Since: 2.26 - */ - - -/** - * g_settings_backend_path_writable_changed: - * @backend: a #GSettingsBackend implementation - * @path: the name of the path - * - * Signals that the writability of all keys below a given path may have - * changed. - * - * Since GSettings performs no locking operations for itself, this call - * will always be made in response to external events. - * - * Since: 2.26 - */ - - -/** - * g_settings_backend_writable_changed: - * @backend: a #GSettingsBackend implementation - * @key: the name of the key - * - * Signals that the writability of a single key has possibly changed. - * - * Since GSettings performs no locking operations for itself, this call - * will always be made in response to external events. - * - * Since: 2.26 - */ - - -/** - * g_settings_bind: - * @settings: a #GSettings object - * @key: the key to bind - * @object: (type GObject.Object): a #GObject - * @property: the name of the property to bind - * @flags: flags for the binding - * - * Create a binding between the @key in the @settings object - * and the property @property of @object. - * - * The binding uses the default GIO mapping functions to map - * between the settings and property values. These functions - * handle booleans, numeric types and string types in a - * straightforward way. Use g_settings_bind_with_mapping() if - * you need a custom mapping, or map between types that are not - * supported by the default mapping functions. - * - * Unless the @flags include %G_SETTINGS_BIND_NO_SENSITIVITY, this - * function also establishes a binding between the writability of - * @key and the "sensitive" property of @object (if @object has - * a boolean property by that name). See g_settings_bind_writable() - * for more details about writable bindings. - * - * Note that the lifecycle of the binding is tied to @object, - * and that you can have only one binding per object property. - * If you bind the same property twice on the same object, the second - * binding overrides the first one. - * - * Since: 2.26 - */ - - -/** - * g_settings_bind_with_mapping: (skip) - * @settings: a #GSettings object - * @key: the key to bind - * @object: (type GObject.Object): a #GObject - * @property: the name of the property to bind - * @flags: flags for the binding - * @get_mapping: a function that gets called to convert values - * from @settings to @object, or %NULL to use the default GIO mapping - * @set_mapping: a function that gets called to convert values - * from @object to @settings, or %NULL to use the default GIO mapping - * @user_data: data that gets passed to @get_mapping and @set_mapping - * @destroy: #GDestroyNotify function for @user_data - * - * Create a binding between the @key in the @settings object - * and the property @property of @object. - * - * The binding uses the provided mapping functions to map between - * settings and property values. - * - * Note that the lifecycle of the binding is tied to @object, - * and that you can have only one binding per object property. - * If you bind the same property twice on the same object, the second - * binding overrides the first one. - * - * Since: 2.26 - */ - - -/** - * g_settings_bind_writable: - * @settings: a #GSettings object - * @key: the key to bind - * @object: (type GObject.Object): a #GObject - * @property: the name of a boolean property to bind - * @inverted: whether to 'invert' the value - * - * Create a binding between the writability of @key in the - * @settings object and the property @property of @object. - * The property must be boolean; "sensitive" or "visible" - * properties of widgets are the most likely candidates. - * - * Writable bindings are always uni-directional; changes of the - * writability of the setting will be propagated to the object - * property, not the other way. - * - * When the @inverted argument is %TRUE, the binding inverts the - * value as it passes from the setting to the object, i.e. @property - * will be set to %TRUE if the key is not writable. - * - * Note that the lifecycle of the binding is tied to @object, - * and that you can have only one binding per object property. - * If you bind the same property twice on the same object, the second - * binding overrides the first one. - * - * Since: 2.26 - */ - - -/** - * g_settings_create_action: - * @settings: a #GSettings - * @key: the name of a key in @settings - * - * Creates a #GAction corresponding to a given #GSettings key. - * - * The action has the same name as the key. - * - * The value of the key becomes the state of the action and the action - * is enabled when the key is writable. Changing the state of the - * action results in the key being written to. Changes to the value or - * writability of the key cause appropriate change notifications to be - * emitted for the action. - * - * For boolean-valued keys, action activations take no parameter and - * result in the toggling of the value. For all other types, - * activations take the new value for the key (which must have the - * correct type). - * - * Returns: (transfer full): a new #GAction - * Since: 2.32 - */ - - -/** - * g_settings_delay: - * @settings: a #GSettings object - * - * Changes the #GSettings object into 'delay-apply' mode. In this - * mode, changes to @settings are not immediately propagated to the - * backend, but kept locally until g_settings_apply() is called. - * - * Since: 2.26 - */ - - -/** - * g_settings_get: - * @settings: a #GSettings object - * @key: the key to get the value for - * @format: a #GVariant format string - * @...: arguments as per @format - * - * Gets the value that is stored at @key in @settings. - * - * A convenience function that combines g_settings_get_value() with - * g_variant_get(). - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or for the #GVariantType of @format to mismatch - * the type given in the schema. - * - * Since: 2.26 - */ - - -/** - * g_settings_get_boolean: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * Gets the value that is stored at @key in @settings. - * - * A convenience variant of g_settings_get() for booleans. - * - * It is a programmer error to give a @key that isn't specified as - * having a boolean type in the schema for @settings. - * - * Returns: a boolean - * Since: 2.26 - */ - - -/** - * g_settings_get_child: - * @settings: a #GSettings object - * @name: the name of the child schema - * - * Creates a child settings object which has a base path of - * `base-path/@name`, where `base-path` is the base path of - * @settings. - * - * The schema for the child settings object must have been declared - * in the schema of @settings using a element. - * - * Returns: (transfer full): a 'child' settings object - * Since: 2.26 - */ - - -/** - * g_settings_get_default_value: - * @settings: a #GSettings object - * @key: the key to get the default value for - * - * Gets the "default value" of a key. - * - * This is the value that would be read if g_settings_reset() were to be - * called on the key. - * - * Note that this may be a different value than returned by - * g_settings_schema_key_get_default_value() if the system administrator - * has provided a default value. - * - * Comparing the return values of g_settings_get_default_value() and - * g_settings_get_value() is not sufficient for determining if a value - * has been set because the user may have explicitly set the value to - * something that happens to be equal to the default. The difference - * here is that if the default changes in the future, the user's key - * will still be set. - * - * This function may be useful for adding an indication to a UI of what - * the default value was before the user set it. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. - * - * Returns: (nullable) (transfer full): the default value - * Since: 2.40 - */ - - -/** - * g_settings_get_double: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * Gets the value that is stored at @key in @settings. - * - * A convenience variant of g_settings_get() for doubles. - * - * It is a programmer error to give a @key that isn't specified as - * having a 'double' type in the schema for @settings. - * - * Returns: a double - * Since: 2.26 - */ - - -/** - * g_settings_get_enum: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * Gets the value that is stored in @settings for @key and converts it - * to the enum value that it represents. - * - * In order to use this function the type of the value must be a string - * and it must be marked in the schema file as an enumerated type. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or is not marked as an enumerated type. - * - * If the value stored in the configuration database is not a valid - * value for the enumerated type then this function will return the - * default value. - * - * Returns: the enum value - * Since: 2.26 - */ - - -/** - * g_settings_get_flags: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * Gets the value that is stored in @settings for @key and converts it - * to the flags value that it represents. - * - * In order to use this function the type of the value must be an array - * of strings and it must be marked in the schema file as a flags type. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or is not marked as a flags type. - * - * If the value stored in the configuration database is not a valid - * value for the flags type then this function will return the default - * value. - * - * Returns: the flags value - * Since: 2.26 - */ - - -/** - * g_settings_get_has_unapplied: - * @settings: a #GSettings object - * - * Returns whether the #GSettings object has any unapplied - * changes. This can only be the case if it is in 'delayed-apply' mode. - * - * Returns: %TRUE if @settings has unapplied changes - * Since: 2.26 - */ - - -/** - * g_settings_get_int: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * Gets the value that is stored at @key in @settings. - * - * A convenience variant of g_settings_get() for 32-bit integers. - * - * It is a programmer error to give a @key that isn't specified as - * having a int32 type in the schema for @settings. - * - * Returns: an integer - * Since: 2.26 - */ - - -/** - * g_settings_get_int64: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * Gets the value that is stored at @key in @settings. - * - * A convenience variant of g_settings_get() for 64-bit integers. - * - * It is a programmer error to give a @key that isn't specified as - * having a int64 type in the schema for @settings. - * - * Returns: a 64-bit integer - * Since: 2.50 - */ - - -/** - * g_settings_get_mapped: - * @settings: a #GSettings object - * @key: the key to get the value for - * @mapping: (scope call): the function to map the value in the - * settings database to the value used by the application - * @user_data: user data for @mapping - * - * Gets the value that is stored at @key in @settings, subject to - * application-level validation/mapping. - * - * You should use this function when the application needs to perform - * some processing on the value of the key (for example, parsing). The - * @mapping function performs that processing. If the function - * indicates that the processing was unsuccessful (due to a parse error, - * for example) then the mapping is tried again with another value. - * - * This allows a robust 'fall back to defaults' behaviour to be - * implemented somewhat automatically. - * - * The first value that is tried is the user's setting for the key. If - * the mapping function fails to map this value, other values may be - * tried in an unspecified order (system or site defaults, translated - * schema default values, untranslated schema default values, etc). - * - * If the mapping function fails for all possible values, one additional - * attempt is made: the mapping function is called with a %NULL value. - * If the mapping function still indicates failure at this point then - * the application will be aborted. - * - * The result parameter for the @mapping function is pointed to a - * #gpointer which is initially set to %NULL. The same pointer is given - * to each invocation of @mapping. The final value of that #gpointer is - * what is returned by this function. %NULL is valid; it is returned - * just as any other value would be. - * - * Returns: (transfer full): the result, which may be %NULL - */ - - -/** - * g_settings_get_range: - * @settings: a #GSettings - * @key: the key to query the range of - * - * Queries the range of a key. - * - * Since: 2.28 - * Deprecated: 2.40: Use g_settings_schema_key_get_range() instead. - */ - - -/** - * g_settings_get_string: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * Gets the value that is stored at @key in @settings. - * - * A convenience variant of g_settings_get() for strings. - * - * It is a programmer error to give a @key that isn't specified as - * having a string type in the schema for @settings. - * - * Returns: a newly-allocated string - * Since: 2.26 - */ - - -/** - * g_settings_get_strv: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * A convenience variant of g_settings_get() for string arrays. - * - * It is a programmer error to give a @key that isn't specified as - * having an array of strings type in the schema for @settings. - * - * Returns: (array zero-terminated=1) (transfer full): a - * newly-allocated, %NULL-terminated array of strings, the value that - * is stored at @key in @settings. - * Since: 2.26 - */ - - -/** - * g_settings_get_uint: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * Gets the value that is stored at @key in @settings. - * - * A convenience variant of g_settings_get() for 32-bit unsigned - * integers. - * - * It is a programmer error to give a @key that isn't specified as - * having a uint32 type in the schema for @settings. - * - * Returns: an unsigned integer - * Since: 2.30 - */ - - -/** - * g_settings_get_uint64: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * Gets the value that is stored at @key in @settings. - * - * A convenience variant of g_settings_get() for 64-bit unsigned - * integers. - * - * It is a programmer error to give a @key that isn't specified as - * having a uint64 type in the schema for @settings. - * - * Returns: a 64-bit unsigned integer - * Since: 2.50 - */ - - -/** - * g_settings_get_user_value: - * @settings: a #GSettings object - * @key: the key to get the user value for - * - * Checks the "user value" of a key, if there is one. - * - * The user value of a key is the last value that was set by the user. - * - * After calling g_settings_reset() this function should always return - * %NULL (assuming something is not wrong with the system - * configuration). - * - * It is possible that g_settings_get_value() will return a different - * value than this function. This can happen in the case that the user - * set a value for a key that was subsequently locked down by the system - * administrator -- this function will return the user's old value. - * - * This function may be useful for adding a "reset" option to a UI or - * for providing indication that a particular value has been changed. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. - * - * Returns: (nullable) (transfer full): the user's value, if set - * Since: 2.40 - */ - - -/** - * g_settings_get_value: - * @settings: a #GSettings object - * @key: the key to get the value for - * - * Gets the value that is stored in @settings for @key. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. - * - * Returns: a new #GVariant - * Since: 2.26 - */ - - -/** - * g_settings_is_writable: - * @settings: a #GSettings object - * @name: the name of a key - * - * Finds out if a key can be written or not - * - * Returns: %TRUE if the key @name is writable - * Since: 2.26 - */ - - -/** - * g_settings_list_children: - * @settings: a #GSettings object - * - * Gets the list of children on @settings. - * - * The list is exactly the list of strings for which it is not an error - * to call g_settings_get_child(). - * - * There is little reason to call this function from "normal" code, since - * you should already know what children are in your schema. This function - * may still be useful there for introspection reasons, however. - * - * You should free the return value with g_strfreev() when you are done - * with it. - * - * Returns: (transfer full) (element-type utf8): a list of the children on - * @settings, in no defined order - */ - - -/** - * g_settings_list_keys: - * @settings: a #GSettings object - * - * Introspects the list of keys on @settings. - * - * You should probably not be calling this function from "normal" code - * (since you should already know what keys are in your schema). This - * function is intended for introspection reasons. - * - * You should free the return value with g_strfreev() when you are done - * with it. - * - * Returns: (transfer full) (element-type utf8): a list of the keys on - * @settings, in no defined order - * Deprecated: 2.46: Use g_settings_schema_list_keys() instead. - */ - - -/** - * g_settings_list_relocatable_schemas: - * - * Deprecated. - * - * Returns: (element-type utf8) (transfer none): a list of relocatable - * #GSettings schemas that are available, in no defined order. The list must - * not be modified or freed. - * Since: 2.28 - * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead - */ - - -/** - * g_settings_list_schemas: - * - * Deprecated. - * - * Returns: (element-type utf8) (transfer none): a list of #GSettings - * schemas that are available, in no defined order. The list must not be - * modified or freed. - * Since: 2.26 - * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead. - * If you used g_settings_list_schemas() to check for the presence of - * a particular schema, use g_settings_schema_source_lookup() instead - * of your whole loop. - */ - - -/** - * g_settings_new: - * @schema_id: the id of the schema - * - * Creates a new #GSettings object with the schema specified by - * @schema_id. - * - * It is an error for the schema to not exist: schemas are an - * essential part of a program, as they provide type information. - * If schemas need to be dynamically loaded (for example, from an - * optional runtime dependency), g_settings_schema_source_lookup() - * can be used to test for their existence before loading them. - * - * Signals on the newly created #GSettings object will be dispatched - * via the thread-default #GMainContext in effect at the time of the - * call to g_settings_new(). The new #GSettings will hold a reference - * on the context. See g_main_context_push_thread_default(). - * - * Returns: a new #GSettings object - * Since: 2.26 - */ - - -/** - * g_settings_new_full: - * @schema: a #GSettingsSchema - * @backend: (nullable): a #GSettingsBackend - * @path: (nullable): the path to use - * - * Creates a new #GSettings object with a given schema, backend and - * path. - * - * It should be extremely rare that you ever want to use this function. - * It is made available for advanced use-cases (such as plugin systems - * that want to provide access to schemas loaded from custom locations, - * etc). - * - * At the most basic level, a #GSettings object is a pure composition of - * 4 things: a #GSettingsSchema, a #GSettingsBackend, a path within that - * backend, and a #GMainContext to which signals are dispatched. - * - * This constructor therefore gives you full control over constructing - * #GSettings instances. The first 3 parameters are given directly as - * @schema, @backend and @path, and the main context is taken from the - * thread-default (as per g_settings_new()). - * - * If @backend is %NULL then the default backend is used. - * - * If @path is %NULL then the path from the schema is used. It is an - * error if @path is %NULL and the schema has no path of its own or if - * @path is non-%NULL and not equal to the path that the schema does - * have. - * - * Returns: a new #GSettings object - * Since: 2.32 - */ - - -/** - * g_settings_new_with_backend: - * @schema_id: the id of the schema - * @backend: the #GSettingsBackend to use - * - * Creates a new #GSettings object with the schema specified by - * @schema_id and a given #GSettingsBackend. - * - * Creating a #GSettings object with a different backend allows accessing - * settings from a database other than the usual one. For example, it may make - * sense to pass a backend corresponding to the "defaults" settings database on - * the system to get a settings object that modifies the system default - * settings instead of the settings for this user. - * - * Returns: a new #GSettings object - * Since: 2.26 - */ - - -/** - * g_settings_new_with_backend_and_path: - * @schema_id: the id of the schema - * @backend: the #GSettingsBackend to use - * @path: the path to use - * - * Creates a new #GSettings object with the schema specified by - * @schema_id and a given #GSettingsBackend and path. - * - * This is a mix of g_settings_new_with_backend() and - * g_settings_new_with_path(). - * - * Returns: a new #GSettings object - * Since: 2.26 - */ - - -/** - * g_settings_new_with_path: - * @schema_id: the id of the schema - * @path: the path to use - * - * Creates a new #GSettings object with the relocatable schema specified - * by @schema_id and a given path. - * - * You only need to do this if you want to directly create a settings - * object with a schema that doesn't have a specified path of its own. - * That's quite rare. - * - * It is a programmer error to call this function for a schema that - * has an explicitly specified path. - * - * It is a programmer error if @path is not a valid path. A valid path - * begins and ends with '/' and does not contain two consecutive '/' - * characters. - * - * Returns: a new #GSettings object - * Since: 2.26 - */ - - -/** - * g_settings_range_check: - * @settings: a #GSettings - * @key: the key to check - * @value: the value to check - * - * Checks if the given @value is of the correct type and within the - * permitted range for @key. - * - * Returns: %TRUE if @value is valid for @key - * Since: 2.28 - * Deprecated: 2.40: Use g_settings_schema_key_range_check() instead. - */ - - -/** - * g_settings_reset: - * @settings: a #GSettings object - * @key: the name of a key - * - * Resets @key to its default value. - * - * This call resets the key, as much as possible, to its default value. - * That might be the value specified in the schema or the one set by the - * administrator. - */ - - -/** - * g_settings_revert: - * @settings: a #GSettings instance - * - * Reverts all non-applied changes to the settings. This function - * does nothing unless @settings is in 'delay-apply' mode; see - * g_settings_delay(). In the normal case settings are always applied - * immediately. - * - * Change notifications will be emitted for affected keys. - */ - - -/** - * g_settings_schema_get_id: - * @schema: a #GSettingsSchema - * - * Get the ID of @schema. - * - * Returns: (transfer none): the ID - */ - - -/** - * g_settings_schema_get_key: - * @schema: a #GSettingsSchema - * @name: the name of a key - * - * Gets the key named @name from @schema. - * - * It is a programmer error to request a key that does not exist. See - * g_settings_schema_list_keys(). - * - * Returns: (transfer full): the #GSettingsSchemaKey for @name - * Since: 2.40 - */ - - -/** - * g_settings_schema_get_path: - * @schema: a #GSettingsSchema - * - * Gets the path associated with @schema, or %NULL. - * - * Schemas may be single-instance or relocatable. Single-instance - * schemas correspond to exactly one set of keys in the backend - * database: those located at the path returned by this function. - * - * Relocatable schemas can be referenced by other schemas and can - * therefore describe multiple sets of keys at different locations. For - * relocatable schemas, this function will return %NULL. - * - * Returns: (nullable) (transfer none): the path of the schema, or %NULL - * Since: 2.32 - */ - - -/** - * g_settings_schema_has_key: - * @schema: a #GSettingsSchema - * @name: the name of a key - * - * Checks if @schema has a key named @name. - * - * Returns: %TRUE if such a key exists - * Since: 2.40 - */ - - -/** - * g_settings_schema_key_get_default_value: - * @key: a #GSettingsSchemaKey - * - * Gets the default value for @key. - * - * Note that this is the default value according to the schema. System - * administrator defaults and lockdown are not visible via this API. - * - * Returns: (transfer full): the default value for the key - * Since: 2.40 - */ - - -/** - * g_settings_schema_key_get_description: - * @key: a #GSettingsSchemaKey - * - * Gets the description for @key. - * - * If no description has been provided in the schema for @key, returns - * %NULL. - * - * The description can be one sentence to several paragraphs in length. - * Paragraphs are delimited with a double newline. Descriptions can be - * translated and the value returned from this function is is the - * current locale. - * - * This function is slow. The summary and description information for - * the schemas is not stored in the compiled schema database so this - * function has to parse all of the source XML files in the schema - * directory. - * - * Returns: (nullable): the description for @key, or %NULL - * Since: 2.34 - */ - - -/** - * g_settings_schema_key_get_name: - * @key: a #GSettingsSchemaKey - * - * Gets the name of @key. - * - * Returns: the name of @key. - * Since: 2.44 - */ - - -/** - * g_settings_schema_key_get_range: - * @key: a #GSettingsSchemaKey - * - * Queries the range of a key. - * - * This function will return a #GVariant that fully describes the range - * of values that are valid for @key. - * - * The type of #GVariant returned is `(sv)`. The string describes - * the type of range restriction in effect. The type and meaning of - * the value contained in the variant depends on the string. - * - * If the string is `'type'` then the variant contains an empty array. - * The element type of that empty array is the expected type of value - * and all values of that type are valid. - * - * If the string is `'enum'` then the variant contains an array - * enumerating the possible values. Each item in the array is - * a possible valid value and no other values are valid. - * - * If the string is `'flags'` then the variant contains an array. Each - * item in the array is a value that may appear zero or one times in an - * array to be used as the value for this key. For example, if the - * variant contained the array `['x', 'y']` then the valid values for - * the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and - * `['y', 'x']`. - * - * Finally, if the string is `'range'` then the variant contains a pair - * of like-typed values -- the minimum and maximum permissible values - * for this key. - * - * This information should not be used by normal programs. It is - * considered to be a hint for introspection purposes. Normal programs - * should already know what is permitted by their own schema. The - * format may change in any way in the future -- but particularly, new - * forms may be added to the possibilities described above. - * - * You should free the returned value with g_variant_unref() when it is - * no longer needed. - * - * Returns: (transfer full): a #GVariant describing the range - * Since: 2.40 - */ - - -/** - * g_settings_schema_key_get_summary: - * @key: a #GSettingsSchemaKey - * - * Gets the summary for @key. - * - * If no summary has been provided in the schema for @key, returns - * %NULL. - * - * The summary is a short description of the purpose of the key; usually - * one short sentence. Summaries can be translated and the value - * returned from this function is is the current locale. - * - * This function is slow. The summary and description information for - * the schemas is not stored in the compiled schema database so this - * function has to parse all of the source XML files in the schema - * directory. - * - * Returns: (nullable): the summary for @key, or %NULL - * Since: 2.34 - */ - - -/** - * g_settings_schema_key_get_value_type: - * @key: a #GSettingsSchemaKey - * - * Gets the #GVariantType of @key. - * - * Returns: (transfer none): the type of @key - * Since: 2.40 - */ - - -/** - * g_settings_schema_key_range_check: - * @key: a #GSettingsSchemaKey - * @value: the value to check - * - * Checks if the given @value is within the - * permitted range for @key. - * - * It is a programmer error if @value is not of the correct type — you - * must check for this first. - * - * Returns: %TRUE if @value is valid for @key - * Since: 2.40 - */ - - -/** - * g_settings_schema_key_ref: - * @key: a #GSettingsSchemaKey - * - * Increase the reference count of @key, returning a new reference. - * - * Returns: a new reference to @key - * Since: 2.40 - */ - - -/** - * g_settings_schema_key_unref: - * @key: a #GSettingsSchemaKey - * - * Decrease the reference count of @key, possibly freeing it. - * - * Since: 2.40 - */ - - -/** - * g_settings_schema_list_children: - * @schema: a #GSettingsSchema - * - * Gets the list of children in @schema. - * - * You should free the return value with g_strfreev() when you are done - * with it. - * - * Returns: (transfer full) (element-type utf8): a list of the children on - * @settings, in no defined order - * Since: 2.44 - */ - - -/** - * g_settings_schema_list_keys: - * @schema: a #GSettingsSchema - * - * Introspects the list of keys on @schema. - * - * You should probably not be calling this function from "normal" code - * (since you should already know what keys are in your schema). This - * function is intended for introspection reasons. - * - * Returns: (transfer full) (element-type utf8): a list of the keys on - * @schema, in no defined order - * Since: 2.46 - */ - - -/** - * g_settings_schema_ref: - * @schema: a #GSettingsSchema - * - * Increase the reference count of @schema, returning a new reference. - * - * Returns: a new reference to @schema - * Since: 2.32 - */ - - -/** - * g_settings_schema_source_get_default: - * - * Gets the default system schema source. - * - * This function is not required for normal uses of #GSettings but it - * may be useful to authors of plugin management systems or to those who - * want to introspect the content of schemas. - * - * If no schemas are installed, %NULL will be returned. - * - * The returned source may actually consist of multiple schema sources - * from different directories, depending on which directories were given - * in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all - * lookups performed against the default source should probably be done - * recursively. - * - * Returns: (transfer none) (nullable): the default schema source - * Since: 2.32 - */ - - -/** - * g_settings_schema_source_list_schemas: - * @source: a #GSettingsSchemaSource - * @recursive: if we should recurse - * @non_relocatable: (out) (transfer full) (array zero-terminated=1): the - * list of non-relocatable schemas, in no defined order - * @relocatable: (out) (transfer full) (array zero-terminated=1): the list - * of relocatable schemas, in no defined order - * - * Lists the schemas in a given source. - * - * If @recursive is %TRUE then include parent sources. If %FALSE then - * only include the schemas from one source (ie: one directory). You - * probably want %TRUE. - * - * Non-relocatable schemas are those for which you can call - * g_settings_new(). Relocatable schemas are those for which you must - * use g_settings_new_with_path(). - * - * Do not call this function from normal programs. This is designed for - * use by database editors, commandline tools, etc. - * - * Since: 2.40 - */ - - -/** - * g_settings_schema_source_lookup: - * @source: a #GSettingsSchemaSource - * @schema_id: a schema ID - * @recursive: %TRUE if the lookup should be recursive - * - * Looks up a schema with the identifier @schema_id in @source. - * - * This function is not required for normal uses of #GSettings but it - * may be useful to authors of plugin management systems or to those who - * want to introspect the content of schemas. - * - * If the schema isn't found directly in @source and @recursive is %TRUE - * then the parent sources will also be checked. - * - * If the schema isn't found, %NULL is returned. - * - * Returns: (nullable) (transfer full): a new #GSettingsSchema - * Since: 2.32 - */ - - -/** - * g_settings_schema_source_new_from_directory: - * @directory: (type filename): the filename of a directory - * @parent: (nullable): a #GSettingsSchemaSource, or %NULL - * @trusted: %TRUE, if the directory is trusted - * @error: a pointer to a #GError pointer set to %NULL, or %NULL - * - * Attempts to create a new schema source corresponding to the contents - * of the given directory. - * - * This function is not required for normal uses of #GSettings but it - * may be useful to authors of plugin management systems. - * - * The directory should contain a file called `gschemas.compiled` as - * produced by the [glib-compile-schemas][glib-compile-schemas] tool. - * - * If @trusted is %TRUE then `gschemas.compiled` is trusted not to be - * corrupted. This assumption has a performance advantage, but can result - * in crashes or inconsistent behaviour in the case of a corrupted file. - * Generally, you should set @trusted to %TRUE for files installed by the - * system and to %FALSE for files in the home directory. - * - * In either case, an empty file or some types of corruption in the file will - * result in %G_FILE_ERROR_INVAL being returned. - * - * If @parent is non-%NULL then there are two effects. - * - * First, if g_settings_schema_source_lookup() is called with the - * @recursive flag set to %TRUE and the schema can not be found in the - * source, the lookup will recurse to the parent. - * - * Second, any references to other schemas specified within this - * source (ie: `child` or `extends`) references may be resolved - * from the @parent. - * - * For this second reason, except in very unusual situations, the - * @parent should probably be given as the default schema source, as - * returned by g_settings_schema_source_get_default(). - * - * Since: 2.32 - */ - - -/** - * g_settings_schema_source_ref: - * @source: a #GSettingsSchemaSource - * - * Increase the reference count of @source, returning a new reference. - * - * Returns: a new reference to @source - * Since: 2.32 - */ - - -/** - * g_settings_schema_source_unref: - * @source: a #GSettingsSchemaSource - * - * Decrease the reference count of @source, possibly freeing it. - * - * Since: 2.32 - */ - - -/** - * g_settings_schema_unref: - * @schema: a #GSettingsSchema - * - * Decrease the reference count of @schema, possibly freeing it. - * - * Since: 2.32 - */ - - -/** - * g_settings_set: - * @settings: a #GSettings object - * @key: the name of the key to set - * @format: a #GVariant format string - * @...: arguments as per @format - * - * Sets @key in @settings to @value. - * - * A convenience function that combines g_settings_set_value() with - * g_variant_new(). - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or for the #GVariantType of @format to mismatch - * the type given in the schema. - * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.26 - */ - - -/** - * g_settings_set_boolean: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to - * - * Sets @key in @settings to @value. - * - * A convenience variant of g_settings_set() for booleans. - * - * It is a programmer error to give a @key that isn't specified as - * having a boolean type in the schema for @settings. - * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.26 - */ - - -/** - * g_settings_set_double: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to - * - * Sets @key in @settings to @value. - * - * A convenience variant of g_settings_set() for doubles. - * - * It is a programmer error to give a @key that isn't specified as - * having a 'double' type in the schema for @settings. - * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.26 - */ - - -/** - * g_settings_set_enum: - * @settings: a #GSettings object - * @key: a key, within @settings - * @value: an enumerated value - * - * Looks up the enumerated type nick for @value and writes it to @key, - * within @settings. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or is not marked as an enumerated type, or for - * @value not to be a valid value for the named type. - * - * After performing the write, accessing @key directly with - * g_settings_get_string() will return the 'nick' associated with - * @value. - * - * Returns: %TRUE, if the set succeeds - */ - - -/** - * g_settings_set_flags: - * @settings: a #GSettings object - * @key: a key, within @settings - * @value: a flags value - * - * Looks up the flags type nicks for the bits specified by @value, puts - * them in an array of strings and writes the array to @key, within - * @settings. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or is not marked as a flags type, or for @value - * to contain any bits that are not value for the named type. - * - * After performing the write, accessing @key directly with - * g_settings_get_strv() will return an array of 'nicks'; one for each - * bit in @value. - * - * Returns: %TRUE, if the set succeeds - */ - - -/** - * g_settings_set_int: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to - * - * Sets @key in @settings to @value. - * - * A convenience variant of g_settings_set() for 32-bit integers. - * - * It is a programmer error to give a @key that isn't specified as - * having a int32 type in the schema for @settings. - * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.26 - */ - - -/** - * g_settings_set_int64: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to - * - * Sets @key in @settings to @value. - * - * A convenience variant of g_settings_set() for 64-bit integers. - * - * It is a programmer error to give a @key that isn't specified as - * having a int64 type in the schema for @settings. - * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.50 - */ - - -/** - * g_settings_set_string: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to - * - * Sets @key in @settings to @value. - * - * A convenience variant of g_settings_set() for strings. - * - * It is a programmer error to give a @key that isn't specified as - * having a string type in the schema for @settings. - * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.26 - */ - - -/** - * g_settings_set_strv: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: (nullable) (array zero-terminated=1): the value to set it to, or %NULL - * - * Sets @key in @settings to @value. - * - * A convenience variant of g_settings_set() for string arrays. If - * @value is %NULL, then @key is set to be the empty array. - * - * It is a programmer error to give a @key that isn't specified as - * having an array of strings type in the schema for @settings. - * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.26 - */ - - -/** - * g_settings_set_uint: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to - * - * Sets @key in @settings to @value. - * - * A convenience variant of g_settings_set() for 32-bit unsigned - * integers. - * - * It is a programmer error to give a @key that isn't specified as - * having a uint32 type in the schema for @settings. - * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.30 - */ - - -/** - * g_settings_set_uint64: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: the value to set it to - * - * Sets @key in @settings to @value. - * - * A convenience variant of g_settings_set() for 64-bit unsigned - * integers. - * - * It is a programmer error to give a @key that isn't specified as - * having a uint64 type in the schema for @settings. - * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.50 - */ - - -/** - * g_settings_set_value: - * @settings: a #GSettings object - * @key: the name of the key to set - * @value: a #GVariant of the correct type - * - * Sets @key in @settings to @value. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings or for @value to have the incorrect type, per - * the schema. - * - * If @value is floating then this function consumes the reference. - * - * Returns: %TRUE if setting the key succeeded, - * %FALSE if the key was not writable - * Since: 2.26 - */ - - -/** - * g_settings_sync: - * - * Ensures that all pending operations are complete for the default backend. - * - * Writes made to a #GSettings are handled asynchronously. For this - * reason, it is very unlikely that the changes have it to disk by the - * time g_settings_set() returns. - * - * This call will block until all of the writes have made it to the - * backend. Since the mainloop is not running, no change notifications - * will be dispatched during this call (but some may be queued by the - * time the call is done). - */ - - -/** - * g_settings_unbind: - * @object: (type GObject.Object): the object - * @property: the property whose binding is removed - * - * Removes an existing binding for @property on @object. - * - * Note that bindings are automatically removed when the - * object is finalized, so it is rarely necessary to call this - * function. - * - * Since: 2.26 - */ - - -/** - * g_simple_action_group_add_entries: - * @simple: a #GSimpleActionGroup - * @entries: (array length=n_entries): a pointer to the first item in - * an array of #GActionEntry structs - * @n_entries: the length of @entries, or -1 - * @user_data: the user data for signal connections - * - * A convenience function for creating multiple #GSimpleAction instances - * and adding them to the action group. - * - * Since: 2.30 - * Deprecated: 2.38: Use g_action_map_add_action_entries() - */ - - -/** - * g_simple_action_group_insert: - * @simple: a #GSimpleActionGroup - * @action: a #GAction - * - * Adds an action to the action group. - * - * If the action group already contains an action with the same name as - * @action then the old action is dropped from the group. - * - * The action group takes its own reference on @action. - * - * Since: 2.28 - * Deprecated: 2.38: Use g_action_map_add_action() - */ - - -/** - * g_simple_action_group_lookup: - * @simple: a #GSimpleActionGroup - * @action_name: the name of an action - * - * Looks up the action with the name @action_name in the group. - * - * If no such action exists, returns %NULL. - * - * Returns: (transfer none): a #GAction, or %NULL - * Since: 2.28 - * Deprecated: 2.38: Use g_action_map_lookup_action() - */ - - -/** - * g_simple_action_group_new: - * - * Creates a new, empty, #GSimpleActionGroup. - * - * Returns: a new #GSimpleActionGroup - * Since: 2.28 - */ - - -/** - * g_simple_action_group_remove: - * @simple: a #GSimpleActionGroup - * @action_name: the name of the action - * - * Removes the named action from the action group. - * - * 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() - */ - - -/** - * g_simple_action_new: - * @name: the name of the action - * @parameter_type: (nullable): the type of parameter that will be passed to - * handlers for the #GSimpleAction::activate signal, or %NULL for no parameter - * - * Creates a new action. - * - * The created action is stateless. See g_simple_action_new_stateful() to create - * an action that has state. - * - * Returns: a new #GSimpleAction - * Since: 2.28 - */ - - -/** - * g_simple_action_new_stateful: - * @name: the name of the action - * @parameter_type: (nullable): the type of the parameter that will be passed to - * handlers for the #GSimpleAction::activate signal, or %NULL for no parameter - * @state: the initial state of the action - * - * Creates a new stateful action. - * - * All future state values must have the same #GVariantType as the initial - * @state. - * - * If the @state #GVariant is floating, it is consumed. - * - * Returns: a new #GSimpleAction - * Since: 2.28 - */ - - -/** - * g_simple_action_set_enabled: - * @simple: a #GSimpleAction - * @enabled: whether the action is enabled - * - * Sets the action as enabled or not. - * - * An action must be enabled in order to be activated or in order to - * have its state changed from outside callers. - * - * This should only be called by the implementor of the action. Users - * of the action should not attempt to modify its enabled flag. - * - * Since: 2.28 - */ - - -/** - * g_simple_action_set_state: - * @simple: a #GSimpleAction - * @value: the new #GVariant for the state - * - * Sets the state of the action. - * - * This directly updates the 'state' property to the given value. - * - * This should only be called by the implementor of the action. Users - * of the action should not attempt to directly modify the 'state' - * 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 - */ - - -/** - * g_simple_action_set_state_hint: - * @simple: a #GSimpleAction - * @state_hint: (nullable): a #GVariant representing the state hint - * - * Sets the state hint for the action. - * - * See g_action_get_state_hint() for more information about - * action state hints. - * - * Since: 2.44 - */ - - -/** - * g_simple_async_report_error_in_idle: (skip) - * @object: (nullable): a #GObject, or %NULL. - * @callback: a #GAsyncReadyCallback. - * @user_data: user data passed to @callback. - * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR). - * @code: a specific error code. - * @format: a formatted error reporting string. - * @...: a list of variables to fill in @format. - * - * Reports an error in an asynchronous function in an idle function by - * directly setting the contents of the #GAsyncResult with the given error - * information. - * - * Deprecated: 2.46: Use g_task_report_error(). - */ - - -/** - * g_simple_async_report_gerror_in_idle: - * @object: (nullable): a #GObject, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. - * @error: the #GError to report - * - * Reports an error in an idle function. Similar to - * g_simple_async_report_error_in_idle(), but takes a #GError rather - * than building a new one. - * - * Deprecated: 2.46: Use g_task_report_error(). - */ - - -/** - * g_simple_async_report_take_gerror_in_idle: (skip) - * @object: (nullable): a #GObject, or %NULL - * @callback: a #GAsyncReadyCallback. - * @user_data: user data passed to @callback. - * @error: the #GError to report - * - * Reports an error in an idle function. Similar to - * g_simple_async_report_gerror_in_idle(), but takes over the caller's - * ownership of @error, so the caller does not have to free it any more. - * - * Since: 2.28 - * Deprecated: 2.46: Use g_task_report_error(). - */ - - -/** - * g_simple_async_result_complete: - * @simple: a #GSimpleAsyncResult. - * - * Completes an asynchronous I/O job immediately. Must be called in - * the thread where the asynchronous result was to be delivered, as it - * invokes the callback directly. If you are in a different thread use - * g_simple_async_result_complete_in_idle(). - * - * Calling this function takes a reference to @simple for as long as - * is needed to complete the call. - * - * Deprecated: 2.46: Use #GTask instead. - */ - - -/** - * g_simple_async_result_complete_in_idle: - * @simple: a #GSimpleAsyncResult. - * - * Completes an asynchronous function in an idle handler in the - * [thread-default main context][g-main-context-push-thread-default] - * of the thread that @simple was initially created in - * (and re-pushes that context around the invocation of the callback). - * - * Calling this function takes a reference to @simple for as long as - * is needed to complete the call. - * - * Deprecated: 2.46: Use #GTask instead. - */ - - -/** - * g_simple_async_result_get_op_res_gboolean: - * @simple: a #GSimpleAsyncResult. - * - * Gets the operation result boolean from within the asynchronous result. - * - * Returns: %TRUE if the operation's result was %TRUE, %FALSE - * if the operation's result was %FALSE. - * Deprecated: 2.46: Use #GTask and g_task_propagate_boolean() instead. - */ - - -/** - * g_simple_async_result_get_op_res_gpointer: (skip) - * @simple: a #GSimpleAsyncResult. - * - * Gets a pointer result as returned by the asynchronous function. - * - * Returns: a pointer from the result. - * Deprecated: 2.46: Use #GTask and g_task_propagate_pointer() instead. - */ - - -/** - * g_simple_async_result_get_op_res_gssize: - * @simple: a #GSimpleAsyncResult. - * - * Gets a gssize from the asynchronous result. - * - * Returns: a gssize returned from the asynchronous function. - * Deprecated: 2.46: Use #GTask and g_task_propagate_int() instead. - */ - - -/** - * g_simple_async_result_get_source_tag: (skip) - * @simple: a #GSimpleAsyncResult. - * - * Gets the source tag for the #GSimpleAsyncResult. - * - * Returns: a #gpointer to the source object for the #GSimpleAsyncResult. - * Deprecated: 2.46.: Use #GTask and g_task_get_source_tag() instead. - */ - - -/** - * g_simple_async_result_is_valid: - * @result: the #GAsyncResult passed to the _finish function. - * @source: (nullable): the #GObject passed to the _finish function. - * @source_tag: (nullable): the asynchronous function. - * - * Ensures that the data passed to the _finish function of an async - * operation is consistent. Three checks are performed. - * - * First, @result is checked to ensure that it is really a - * #GSimpleAsyncResult. Second, @source is checked to ensure that it - * matches the source object of @result. Third, @source_tag is - * checked to ensure that it is equal to the @source_tag argument given - * to g_simple_async_result_new() (which, by convention, is a pointer - * to the _async function corresponding to the _finish function from - * which this function is called). (Alternatively, if either - * @source_tag or @result's source tag is %NULL, then the source tag - * check is skipped.) - * - * Returns: #TRUE if all checks passed or #FALSE if any failed. - * Since: 2.20 - * Deprecated: 2.46: Use #GTask and g_task_is_valid() instead. - */ - - -/** - * g_simple_async_result_new: - * @source_object: (nullable): a #GObject, or %NULL. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. - * @source_tag: the asynchronous function. - * - * Creates a #GSimpleAsyncResult. - * - * The common convention is to create the #GSimpleAsyncResult in the - * function that starts the asynchronous operation and use that same - * function as the @source_tag. - * - * If your operation supports cancellation with #GCancellable (which it - * probably should) then you should provide the user's cancellable to - * g_simple_async_result_set_check_cancellable() immediately after - * this function returns. - * - * Returns: a #GSimpleAsyncResult. - * Deprecated: 2.46: Use g_task_new() instead. - */ - - -/** - * g_simple_async_result_new_error: - * @source_object: (nullable): a #GObject, or %NULL. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. - * @domain: a #GQuark. - * @code: an error code. - * @format: a string with format characters. - * @...: a list of values to insert into @format. - * - * Creates a new #GSimpleAsyncResult with a set error. - * - * Returns: a #GSimpleAsyncResult. - * Deprecated: 2.46: Use g_task_new() and g_task_return_new_error() instead. - */ - - -/** - * g_simple_async_result_new_from_error: - * @source_object: (nullable): a #GObject, or %NULL. - * @callback: (scope async): a #GAsyncReadyCallback. - * @user_data: (closure): user data passed to @callback. - * @error: a #GError - * - * Creates a #GSimpleAsyncResult from an error condition. - * - * Returns: a #GSimpleAsyncResult. - * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead. - */ - - -/** - * g_simple_async_result_new_take_error: (skip) - * @source_object: (nullable): a #GObject, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data passed to @callback - * @error: a #GError - * - * Creates a #GSimpleAsyncResult from an error condition, and takes over the - * caller's ownership of @error, so the caller does not need to free it anymore. - * - * Returns: a #GSimpleAsyncResult - * Since: 2.28 - * Deprecated: 2.46: Use g_task_new() and g_task_return_error() instead. - */ - - -/** - * g_simple_async_result_propagate_error: - * @simple: a #GSimpleAsyncResult. - * @dest: (out): a location to propagate the error to. - * - * Propagates an error from within the simple asynchronous result to - * a given destination. - * - * If the #GCancellable given to a prior call to - * g_simple_async_result_set_check_cancellable() is cancelled then this - * function will return %TRUE with @dest set appropriately. - * - * Returns: %TRUE if the error was propagated to @dest. %FALSE otherwise. - * Deprecated: 2.46: Use #GTask instead. - */ - - -/** - * g_simple_async_result_run_in_thread: (skip) - * @simple: a #GSimpleAsyncResult. - * @func: a #GSimpleAsyncThreadFunc. - * @io_priority: the io priority of the request. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * - * Runs the asynchronous job in a separate thread and then calls - * g_simple_async_result_complete_in_idle() on @simple to return - * the result to the appropriate main loop. - * - * Calling this function takes a reference to @simple for as long as - * is needed to run the job and report its completion. - * - * Deprecated: 2.46: Use #GTask and g_task_run_in_thread() instead. - */ - - -/** - * g_simple_async_result_set_check_cancellable: - * @simple: a #GSimpleAsyncResult - * @check_cancellable: (nullable): a #GCancellable to check, or %NULL to unset - * - * Sets a #GCancellable to check before dispatching results. - * - * This function has one very specific purpose: the provided cancellable - * is checked at the time of g_simple_async_result_propagate_error() If - * it is cancelled, these functions will return an "Operation was - * cancelled" error (%G_IO_ERROR_CANCELLED). - * - * Implementors of cancellable asynchronous functions should use this in - * order to provide a guarantee to their callers that cancelling an - * async operation will reliably result in an error being returned for - * that operation (even if a positive result for the operation has - * already been sent as an idle to the main context to be dispatched). - * - * The checking described above is done regardless of any call to the - * unrelated g_simple_async_result_set_handle_cancellation() function. - * - * Since: 2.32 - * Deprecated: 2.46: Use #GTask instead. - */ - - -/** - * g_simple_async_result_set_error: (skip) - * @simple: a #GSimpleAsyncResult. - * @domain: a #GQuark (usually #G_IO_ERROR). - * @code: an error code. - * @format: a formatted error reporting string. - * @...: a list of variables to fill in @format. - * - * Sets an error within the asynchronous result without a #GError. - * - * Deprecated: 2.46: Use #GTask and g_task_return_new_error() instead. - */ - - -/** - * g_simple_async_result_set_error_va: (skip) - * @simple: a #GSimpleAsyncResult. - * @domain: a #GQuark (usually #G_IO_ERROR). - * @code: an error code. - * @format: a formatted error reporting string. - * @args: va_list of arguments. - * - * Sets an error within the asynchronous result without a #GError. - * Unless writing a binding, see g_simple_async_result_set_error(). - * - * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. - */ - - -/** - * g_simple_async_result_set_from_error: - * @simple: a #GSimpleAsyncResult. - * @error: #GError. - * - * Sets the result from a #GError. - * - * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. - */ - - -/** - * g_simple_async_result_set_handle_cancellation: - * @simple: a #GSimpleAsyncResult. - * @handle_cancellation: a #gboolean. - * - * Sets whether to handle cancellation within the asynchronous operation. - * - * This function has nothing to do with - * g_simple_async_result_set_check_cancellable(). It only refers to the - * #GCancellable passed to g_simple_async_result_run_in_thread(). - * - * Deprecated: 2.46 - */ - - -/** - * g_simple_async_result_set_op_res_gboolean: - * @simple: a #GSimpleAsyncResult. - * @op_res: a #gboolean. - * - * Sets the operation result to a boolean within the asynchronous result. - * - * Deprecated: 2.46: Use #GTask and g_task_return_boolean() instead. - */ - - -/** - * g_simple_async_result_set_op_res_gpointer: (skip) - * @simple: a #GSimpleAsyncResult. - * @op_res: a pointer result from an asynchronous function. - * @destroy_op_res: a #GDestroyNotify function. - * - * Sets the operation result within the asynchronous result to a pointer. - * - * Deprecated: 2.46: Use #GTask and g_task_return_pointer() instead. - */ - - -/** - * g_simple_async_result_set_op_res_gssize: - * @simple: a #GSimpleAsyncResult. - * @op_res: a #gssize. - * - * Sets the operation result within the asynchronous result to - * the given @op_res. - * - * Deprecated: 2.46: Use #GTask and g_task_return_int() instead. - */ - - -/** - * g_simple_async_result_take_error: (skip) - * @simple: a #GSimpleAsyncResult - * @error: a #GError - * - * Sets the result from @error, and takes over the caller's ownership - * of @error, so the caller does not need to free it any more. - * - * Since: 2.28 - * Deprecated: 2.46: Use #GTask and g_task_return_error() instead. - */ - - -/** - * g_simple_io_stream_new: - * @input_stream: a #GInputStream. - * @output_stream: a #GOutputStream. - * - * Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream. - * See also #GIOStream. - * - * Returns: a new #GSimpleIOStream instance. - * Since: 2.44 - */ - - -/** - * g_simple_permission_new: - * @allowed: %TRUE if the action is allowed - * - * Creates a new #GPermission instance that represents an action that is - * either always or never allowed. - * - * Returns: the #GSimplePermission, as a #GPermission - * Since: 2.26 - */ - - -/** - * g_simple_proxy_resolver_new: - * @default_proxy: (nullable): the default proxy to use, eg - * "socks://192.168.1.1" - * @ignore_hosts: (nullable): 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: (transfer full): 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 "socks://", - * #GSimpleProxyResolver will treat it as referring to all three of - * the socks5, socks4a, and socks4 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 - * "socks://", #GSimpleProxyResolver will treat it - * as referring to all three of the socks5, socks4a, and socks4 proxy - * types. - * - * Since: 2.36 - */ - - -/** - * g_socket_accept: - * @socket: a #GSocket. - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Accept incoming connections on a connection-based socket. This removes - * the first outstanding connection request from the listening socket and - * creates a #GSocket object for it. - * - * The @socket must be bound to a local address with g_socket_bind() and - * must be listening for incoming connections (g_socket_listen()). - * - * If there are no outstanding connections then the operation will block - * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. - * To be notified of an incoming connection, wait for the %G_IO_IN condition. - * - * Returns: (transfer full): a new #GSocket, or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_socket_address_enumerator_next: - * @enumerator: a #GSocketAddressEnumerator - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: a #GError. - * - * Retrieves the next #GSocketAddress from @enumerator. Note that this - * may block for some amount of time. (Eg, a #GNetworkAddress may need - * to do a DNS lookup before it can return an address.) Use - * g_socket_address_enumerator_next_async() if you need to avoid - * blocking. - * - * If @enumerator is expected to yield addresses, but for some reason - * is unable to (eg, because of a DNS error), then the first call to - * g_socket_address_enumerator_next() will return an appropriate error - * in *@error. However, if the first call to - * g_socket_address_enumerator_next() succeeds, then any further - * internal errors (other than @cancellable being triggered) will be - * ignored. - * - * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on - * error (in which case *@error will be set) or if there are no - * more addresses. - */ - - -/** - * g_socket_address_enumerator_next_async: - * @enumerator: a #GSocketAddressEnumerator - * @cancellable: (nullable): 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 - * - * Asynchronously retrieves the next #GSocketAddress from @enumerator - * and then calls @callback, which must call - * g_socket_address_enumerator_next_finish() to get the result. - * - * It is an error to call this multiple times before the previous callback has finished. - */ - - -/** - * g_socket_address_enumerator_next_finish: - * @enumerator: a #GSocketAddressEnumerator - * @result: a #GAsyncResult - * @error: a #GError - * - * Retrieves the result of a completed call to - * g_socket_address_enumerator_next_async(). See - * g_socket_address_enumerator_next() for more information about - * error handling. - * - * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on - * error (in which case *@error will be set) or if there are no - * more addresses. - */ - - -/** - * g_socket_address_get_family: - * @address: a #GSocketAddress - * - * Gets the socket family type of @address. - * - * Returns: the socket family type of @address - * Since: 2.22 - */ - - -/** - * g_socket_address_get_native_size: - * @address: a #GSocketAddress - * - * Gets the size of @address's native struct sockaddr. - * You can use this to allocate memory to pass to - * g_socket_address_to_native(). - * - * Returns: the size of the native struct sockaddr that - * @address represents - * Since: 2.22 - */ - - -/** - * g_socket_address_new_from_native: - * @native: (not nullable): a pointer to a struct sockaddr - * @len: the size of the memory location pointed to by @native - * - * Creates a #GSocketAddress subclass corresponding to the native - * struct sockaddr @native. - * - * Returns: a new #GSocketAddress if @native could successfully - * be converted, otherwise %NULL - * Since: 2.22 - */ - - -/** - * g_socket_address_to_native: - * @address: a #GSocketAddress - * @dest: a pointer to a memory location that will contain the native - * struct sockaddr - * @destlen: the size of @dest. Must be at least as large as - * g_socket_address_get_native_size() - * @error: #GError for error reporting, or %NULL to ignore - * - * Converts a #GSocketAddress to a native struct sockaddr, which can - * be passed to low-level functions like connect() or bind(). - * - * If not enough space is available, a %G_IO_ERROR_NO_SPACE error - * is returned. If the address type is not known on the system - * then a %G_IO_ERROR_NOT_SUPPORTED error is returned. - * - * Returns: %TRUE if @dest was filled in, %FALSE on error - * Since: 2.22 - */ - - -/** - * g_socket_bind: - * @socket: a #GSocket. - * @address: a #GSocketAddress specifying the local address. - * @allow_reuse: whether to allow reusing this address - * @error: #GError for error reporting, or %NULL to ignore. - * - * When a socket is created it is attached to an address family, but it - * doesn't have an address in this family. g_socket_bind() assigns the - * address (sometimes called name) of the socket. - * - * It is generally required to bind to a local address before you can - * receive connections. (See g_socket_listen() and g_socket_accept() ). - * In certain situations, you may also want to bind a socket that will be - * used to initiate connections, though this is not normally required. - * - * If @socket is a TCP socket, then @allow_reuse controls the setting - * of the `SO_REUSEADDR` 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 - */ - - -/** - * g_socket_check_connect_result: - * @socket: a #GSocket - * @error: #GError for error reporting, or %NULL to ignore. - * - * Checks and resets the pending connect error for the socket. - * This is used to check for errors when g_socket_connect() is - * used in non-blocking mode. - * - * Returns: %TRUE if no error, %FALSE otherwise, setting @error to the error - * Since: 2.22 - */ - - -/** - * g_socket_client_add_application_proxy: - * @client: a #GSocketClient - * @protocol: The proxy protocol - * - * Enable proxy protocols to be handled by the application. When the - * indicated proxy protocol is returned by the #GProxyResolver, - * #GSocketClient will consider this protocol as supported but will - * not try to find a #GProxy instance to handle handshaking. The - * application must check for this case by calling - * g_socket_connection_get_remote_address() on the returned - * #GSocketConnection, and seeing if it's a #GProxyAddress of the - * appropriate type, to determine whether or not it needs to handle - * the proxy handshaking itself. - * - * This should be used for proxy protocols that are dialects of - * another protocol such as HTTP proxy. It also allows cohabitation of - * proxy protocols that are reused between protocols. A good example - * is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also - * be use as generic socket proxy through the HTTP CONNECT method. - * - * When the proxy is detected as being an application proxy, TLS handshake - * will be skipped. This is required to let the application do the proxy - * specific handshake. - */ - - -/** - * g_socket_client_connect: - * @client: a #GSocketClient. - * @connectable: a #GSocketConnectable specifying the remote address. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Tries to resolve the @connectable and make a network connection to it. - * - * Upon a successful connection, a new #GSocketConnection is constructed - * and returned. The caller owns this new object and must drop their - * reference to it when finished with it. - * - * The type of the #GSocketConnection object returned depends on the type of - * the underlying socket that is used. For instance, for a TCP/IP connection - * it will be a #GTcpConnection. - * - * The socket created will be the same family as the address that the - * @connectable resolves to, unless family is set with g_socket_client_set_family() - * or indirectly via g_socket_client_set_local_address(). The socket type - * defaults to %G_SOCKET_TYPE_STREAM but can be set with - * g_socket_client_set_socket_type(). - * - * If a local address is specified with g_socket_client_set_local_address() the - * socket will be bound to this address before connecting. - * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 - */ - - -/** - * g_socket_client_connect_async: - * @client: a #GSocketClient - * @connectable: a #GSocketConnectable specifying the remote address. - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback - * - * This is the asynchronous version of g_socket_client_connect(). - * - * You may wish to prefer the asynchronous version even in synchronous - * command line programs because, since 2.60, it implements - * [RFC 8305](https://tools.ietf.org/html/rfc8305) "Happy Eyeballs" - * recommendations to work around long connection timeouts in networks - * where IPv6 is broken by performing an IPv4 connection simultaneously - * without waiting for IPv6 to time out, which is not supported by the - * synchronous call. (This is not an API guarantee, and may change in - * the future.) - * - * When the operation is finished @callback will be - * called. You can then call g_socket_client_connect_finish() to get - * the result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_socket_client_connect_finish: - * @client: a #GSocketClient. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes an async connect operation. See g_socket_client_connect_async() - * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 - */ - - -/** - * g_socket_client_connect_to_host: - * @client: a #GSocketClient - * @host_and_port: the name and optionally port of the host to connect to - * @default_port: the default port to connect to - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a pointer to a #GError, or %NULL - * - * This is a helper function for g_socket_client_connect(). - * - * Attempts to create a TCP connection to the named host. - * - * @host_and_port may be in any of a number of recognized formats; an IPv6 - * address, an IPv4 address, or a domain name (in which case a DNS - * lookup is performed). Quoting with [] is supported for all address - * types. A port override may be specified in the usual way with a - * colon. Ports may be given as decimal numbers or symbolic names (in - * which case an /etc/services lookup is performed). - * - * If no port override is given in @host_and_port then @default_port will be - * used as the port number to connect to. - * - * In general, @host_and_port is expected to be provided by the user (allowing - * them to give the hostname, and a port override if necessary) and - * @default_port is expected to be provided by the application. - * - * In the case that an IP address is given, a single connection - * attempt is made. In the case that a name is given, multiple - * connection attempts may be made, in turn and according to the - * number of address records in DNS, until a connection succeeds. - * - * Upon a successful connection, a new #GSocketConnection is constructed - * and returned. The caller owns this new object and must drop their - * reference to it when finished with it. - * - * In the event of any failure (DNS error, service not found, no hosts - * connectable) %NULL is returned and @error (if non-%NULL) is set - * accordingly. - * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 - */ - - -/** - * g_socket_client_connect_to_host_async: - * @client: a #GSocketClient - * @host_and_port: the name and optionally the port of the host to connect to - * @default_port: the default port to connect to - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback - * - * This is the asynchronous version of g_socket_client_connect_to_host(). - * - * When the operation is finished @callback will be - * called. You can then call g_socket_client_connect_to_host_finish() to get - * the result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_socket_client_connect_to_host_finish: - * @client: a #GSocketClient. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes an async connect operation. See g_socket_client_connect_to_host_async() - * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 - */ - - -/** - * g_socket_client_connect_to_service: - * @client: a #GSocketConnection - * @domain: a domain name - * @service: the name of the service to connect to - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a pointer to a #GError, or %NULL - * - * Attempts to create a TCP connection to a service. - * - * This call looks up the SRV record for @service at @domain for the - * "tcp" protocol. It then attempts to connect, in turn, to each of - * the hosts providing the service until either a connection succeeds - * or there are no hosts remaining. - * - * Upon a successful connection, a new #GSocketConnection is constructed - * and returned. The caller owns this new object and must drop their - * reference to it when finished with it. - * - * In the event of any failure (DNS error, service not found, no hosts - * connectable) %NULL is returned and @error (if non-%NULL) is set - * accordingly. - * - * Returns: (transfer full): a #GSocketConnection if successful, or %NULL on error - */ - - -/** - * g_socket_client_connect_to_service_async: - * @client: a #GSocketClient - * @domain: a domain name - * @service: the name of the service to connect to - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback - * - * This is the asynchronous version of - * g_socket_client_connect_to_service(). - * - * Since: 2.22 - */ - - -/** - * g_socket_client_connect_to_service_finish: - * @client: a #GSocketClient. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes an async connect operation. See g_socket_client_connect_to_service_async() - * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 - */ - - -/** - * g_socket_client_connect_to_uri: - * @client: a #GSocketClient - * @uri: A network URI - * @default_port: the default port to connect to - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a pointer to a #GError, or %NULL - * - * This is a helper function for g_socket_client_connect(). - * - * Attempts to create a TCP connection with a network URI. - * - * @uri may be any valid URI containing an "authority" (hostname/port) - * component. If a port is not specified in the URI, @default_port - * will be used. TLS will be negotiated if #GSocketClient:tls is %TRUE. - * (#GSocketClient does not know to automatically assume TLS for - * certain URI schemes.) - * - * Using this rather than g_socket_client_connect() or - * g_socket_client_connect_to_host() allows #GSocketClient to - * determine when to use application-specific proxy protocols. - * - * Upon a successful connection, a new #GSocketConnection is constructed - * and returned. The caller owns this new object and must drop their - * reference to it when finished with it. - * - * In the event of any failure (DNS error, service not found, no hosts - * connectable) %NULL is returned and @error (if non-%NULL) is set - * accordingly. - * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.26 - */ - - -/** - * g_socket_client_connect_to_uri_async: - * @client: a #GSocketClient - * @uri: a network uri - * @default_port: the default port to connect to - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback - * - * This is the asynchronous version of g_socket_client_connect_to_uri(). - * - * When the operation is finished @callback will be - * called. You can then call g_socket_client_connect_to_uri_finish() to get - * the result of the operation. - * - * Since: 2.26 - */ - - -/** - * g_socket_client_connect_to_uri_finish: - * @client: a #GSocketClient. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes an async connect operation. See g_socket_client_connect_to_uri_async() - * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.26 - */ - - -/** - * g_socket_client_get_enable_proxy: - * @client: a #GSocketClient. - * - * Gets the proxy enable state; see g_socket_client_set_enable_proxy() - * - * Returns: whether proxying is enabled - * Since: 2.26 - */ - - -/** - * g_socket_client_get_family: - * @client: a #GSocketClient. - * - * Gets the socket family of the socket client. - * - * See g_socket_client_set_family() for details. - * - * Returns: a #GSocketFamily - * Since: 2.22 - */ - - -/** - * g_socket_client_get_local_address: - * @client: a #GSocketClient. - * - * Gets the local address of the socket client. - * - * See g_socket_client_set_local_address() for details. - * - * Returns: (nullable) (transfer none): a #GSocketAddress or %NULL. Do not free. - * Since: 2.22 - */ - - -/** - * g_socket_client_get_protocol: - * @client: a #GSocketClient - * - * Gets the protocol name type of the socket client. - * - * See g_socket_client_set_protocol() for details. - * - * Returns: a #GSocketProtocol - * Since: 2.22 - */ - - -/** - * 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. - * - * Gets the socket type of the socket client. - * - * See g_socket_client_set_socket_type() for details. - * - * Returns: a #GSocketFamily - * Since: 2.22 - */ - - -/** - * g_socket_client_get_timeout: - * @client: a #GSocketClient - * - * Gets the I/O timeout time for sockets created by @client. - * - * See g_socket_client_set_timeout() for details. - * - * Returns: the timeout in seconds - * Since: 2.26 - */ - - -/** - * g_socket_client_get_tls: - * @client: a #GSocketClient. - * - * Gets whether @client creates TLS connections. See - * g_socket_client_set_tls() for details. - * - * Returns: whether @client uses TLS - * Since: 2.28 - */ - - -/** - * g_socket_client_get_tls_validation_flags: - * @client: a #GSocketClient. - * - * Gets the TLS validation flags used creating TLS connections via - * @client. - * - * Returns: the TLS validation flags - * Since: 2.28 - */ - - -/** - * g_socket_client_new: - * - * Creates a new #GSocketClient with the default options. - * - * Returns: a #GSocketClient. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_socket_client_set_enable_proxy: - * @client: a #GSocketClient. - * @enable: whether to enable proxies - * - * Sets whether or not @client attempts to make connections via a - * proxy server. When enabled (the default), #GSocketClient will use a - * #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 - */ - - -/** - * g_socket_client_set_family: - * @client: a #GSocketClient. - * @family: a #GSocketFamily - * - * Sets the socket family of the socket client. - * If this is set to something other than %G_SOCKET_FAMILY_INVALID - * then the sockets created by this object will be of the specified - * family. - * - * This might be useful for instance if you want to force the local - * connection to be an ipv4 socket, even though the address might - * be an ipv6 mapped to ipv4 address. - * - * Since: 2.22 - */ - - -/** - * g_socket_client_set_local_address: - * @client: a #GSocketClient. - * @address: (nullable): a #GSocketAddress, or %NULL - * - * Sets the local address of the socket client. - * The sockets created by this object will bound to the - * specified address (if not %NULL) before connecting. - * - * This is useful if you want to ensure that the local - * side of the connection is on a specific port, or on - * a specific interface. - * - * Since: 2.22 - */ - - -/** - * g_socket_client_set_protocol: - * @client: a #GSocketClient. - * @protocol: a #GSocketProtocol - * - * Sets the protocol of the socket client. - * The sockets created by this object will use of the specified - * protocol. - * - * If @protocol is %G_SOCKET_PROTOCOL_DEFAULT that means to use the default - * protocol for the socket family and type. - * - * Since: 2.22 - */ - - -/** - * g_socket_client_set_proxy_resolver: - * @client: a #GSocketClient. - * @proxy_resolver: (nullable): 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 - * - * Sets the socket type of the socket client. - * The sockets created by this object will be of the specified - * type. - * - * It doesn't make sense to specify a type of %G_SOCKET_TYPE_DATAGRAM, - * as GSocketClient is used for connection oriented services. - * - * Since: 2.22 - */ - - -/** - * g_socket_client_set_timeout: - * @client: a #GSocketClient. - * @timeout: the timeout - * - * Sets the I/O timeout for sockets created by @client. @timeout is a - * time in seconds, or 0 for no timeout (the default). - * - * The timeout value affects the initial connection attempt as well, - * so setting this may cause calls to g_socket_client_connect(), etc, - * to fail with %G_IO_ERROR_TIMED_OUT. - * - * Since: 2.26 - */ - - -/** - * g_socket_client_set_tls: - * @client: a #GSocketClient. - * @tls: whether to use TLS - * - * Sets whether @client creates TLS (aka SSL) connections. If @tls is - * %TRUE, @client will wrap its connections in a #GTlsClientConnection - * and perform a TLS handshake when connecting. - * - * Note that since #GSocketClient must return a #GSocketConnection, - * but #GTlsClientConnection is not a #GSocketConnection, this - * actually wraps the resulting #GTlsClientConnection in a - * #GTcpWrapperConnection when returning it. You can use - * g_tcp_wrapper_connection_get_base_io_stream() on the return value - * to extract the #GTlsClientConnection. - * - * If you need to modify the behavior of the TLS handshake (eg, by - * setting a client-side certificate to use, or connecting to the - * #GTlsConnection::accept-certificate signal), you can connect to - * @client's #GSocketClient::event signal and wait for it to be - * emitted with %G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you - * a chance to see the #GTlsClientConnection before the handshake - * starts. - * - * Since: 2.28 - */ - - -/** - * g_socket_client_set_tls_validation_flags: - * @client: a #GSocketClient. - * @flags: the validation flags - * - * Sets the TLS validation flags used when creating TLS connections - * via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. - * - * Since: 2.28 - */ - - -/** - * g_socket_close: - * @socket: a #GSocket - * @error: #GError for error reporting, or %NULL to ignore. - * - * Closes the socket, shutting down any active connection. - * - * Closing a socket does not wait for all outstanding I/O operations - * to finish, so the caller should not rely on them to be guaranteed - * to complete even if the close returns with no error. - * - * Once the socket is closed, all other operations will return - * %G_IO_ERROR_CLOSED. Closing a socket multiple times will not - * return an error. - * - * Sockets will be automatically closed when the last reference - * is dropped, but you might want to call this function to make sure - * resources are released as early as possible. - * - * Beware that due to the way that TCP works, it is possible for - * recently-sent data to be lost if either you close a socket while the - * %G_IO_IN condition is set, or else if the remote connection tries to - * send something to you after you close the socket but before it has - * finished reading all of the data you sent. There is no easy generic - * way to avoid this problem; the easiest fix is to design the network - * protocol such that the client will never send data "out of turn". - * Another solution is for the server to half-close the connection by - * calling g_socket_shutdown() with only the @shutdown_write flag set, - * and then wait for the client to notice this and close its side of the - * connection, after which the server can safely call g_socket_close(). - * (This is what #GTcpConnection does if you call - * g_tcp_connection_set_graceful_disconnect(). But of course, this - * only works if the client will close its connection after the server - * does.) - * - * Returns: %TRUE on success, %FALSE on error - * Since: 2.22 - */ - - -/** - * g_socket_condition_check: - * @socket: a #GSocket - * @condition: a #GIOCondition mask to check - * - * Checks on the readiness of @socket to perform operations. - * The operations specified in @condition are checked for and masked - * against the currently-satisfied conditions on @socket. The result - * is returned. - * - * Note that on Windows, it is possible for an operation to return - * %G_IO_ERROR_WOULD_BLOCK even immediately after - * g_socket_condition_check() has claimed that the socket is ready for - * writing. Rather than calling g_socket_condition_check() and then - * writing to the socket if it succeeds, it is generally better to - * simply try writing to the socket right away, and try again later if - * the initial attempt returns %G_IO_ERROR_WOULD_BLOCK. - * - * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in condition; - * these conditions will always be set in the output if they are true. - * - * This call never blocks. - * - * Returns: the @GIOCondition mask of the current state - * Since: 2.22 - */ - - -/** - * g_socket_condition_timed_wait: - * @socket: a #GSocket - * @condition: a #GIOCondition mask to wait for - * @timeout_us: the maximum time (in microseconds) to wait, or -1 - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError pointer, or %NULL - * - * Waits for up to @timeout_us microseconds for @condition to become true - * on @socket. If the condition is met, %TRUE is returned. - * - * If @cancellable is cancelled before the condition is met, or if - * @timeout_us (or the socket's #GSocket:timeout) is reached before the - * condition is met, then %FALSE is returned and @error, if non-%NULL, - * is set to the appropriate value (%G_IO_ERROR_CANCELLED or - * %G_IO_ERROR_TIMED_OUT). - * - * If you don't want a timeout, use g_socket_condition_wait(). - * (Alternatively, you can pass -1 for @timeout_us.) - * - * Note that although @timeout_us is in microseconds for consistency with - * other GLib APIs, this function actually only has millisecond - * resolution, and the behavior is undefined if @timeout_us is not an - * exact number of milliseconds. - * - * Returns: %TRUE if the condition was met, %FALSE otherwise - * Since: 2.32 - */ - - -/** - * g_socket_condition_wait: - * @socket: a #GSocket - * @condition: a #GIOCondition mask to wait for - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError pointer, or %NULL - * - * Waits for @condition to become true on @socket. When the condition - * is met, %TRUE is returned. - * - * If @cancellable is cancelled before the condition is met, or if the - * socket has a timeout set and it is reached before the condition is - * met, then %FALSE is returned and @error, if non-%NULL, is set to - * the appropriate value (%G_IO_ERROR_CANCELLED or - * %G_IO_ERROR_TIMED_OUT). - * - * See also g_socket_condition_timed_wait(). - * - * Returns: %TRUE if the condition was met, %FALSE otherwise - * Since: 2.22 - */ - - -/** - * g_socket_connect: - * @socket: a #GSocket. - * @address: a #GSocketAddress specifying the remote address. - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Connect the socket to the specified remote address. - * - * For connection oriented socket this generally means we attempt to make - * a connection to the @address. For a connection-less socket it sets - * the default address for g_socket_send() and discards all incoming datagrams - * from other sources. - * - * Generally connection oriented sockets can only connect once, but - * connection-less sockets can connect multiple times to change the - * default address. - * - * If the connect call needs to do network I/O it will block, unless - * non-blocking I/O is enabled. Then %G_IO_ERROR_PENDING is returned - * and the user can be notified of the connection finishing by waiting - * for the G_IO_OUT condition. The result of the connection must then be - * checked with g_socket_check_connect_result(). - * - * Returns: %TRUE if connected, %FALSE on error. - * Since: 2.22 - */ - - -/** - * g_socket_connectable_enumerate: - * @connectable: a #GSocketConnectable - * - * Creates a #GSocketAddressEnumerator for @connectable. - * - * Returns: (transfer full): a new #GSocketAddressEnumerator. - * Since: 2.22 - */ - - -/** - * g_socket_connectable_proxy_enumerate: - * @connectable: a #GSocketConnectable - * - * Creates a #GSocketAddressEnumerator for @connectable that will - * return a #GProxyAddress for each of its addresses that you must connect - * to via a proxy. - * - * If @connectable does not implement - * g_socket_connectable_proxy_enumerate(), this will fall back to - * calling g_socket_connectable_enumerate(). - * - * Returns: (transfer full): a new #GSocketAddressEnumerator. - * Since: 2.26 - */ - - -/** - * g_socket_connectable_to_string: - * @connectable: a #GSocketConnectable - * - * Format a #GSocketConnectable as a string. This is a human-readable format for - * use in debugging output, and is not a stable serialization format. It is not - * suitable for use in user interfaces as it exposes too much information for a - * user. - * - * If the #GSocketConnectable implementation does not support string formatting, - * the implementation’s type name will be returned as a fallback. - * - * Returns: (transfer full): the formatted string - * Since: 2.48 - */ - - -/** - * g_socket_connection_connect: - * @connection: a #GSocketConnection - * @address: a #GSocketAddress specifying the remote address. - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Connect @connection to the specified remote address. - * - * Returns: %TRUE if the connection succeeded, %FALSE on error - * Since: 2.32 - */ - - -/** - * g_socket_connection_connect_async: - * @connection: a #GSocketConnection - * @address: a #GSocketAddress specifying the remote address. - * @cancellable: (nullable): a %GCancellable or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback - * - * Asynchronously connect @connection to the specified remote address. - * - * This clears the #GSocket:blocking flag on @connection's underlying - * socket if it is currently set. - * - * Use g_socket_connection_connect_finish() to retrieve the result. - * - * Since: 2.32 - */ - - -/** - * g_socket_connection_connect_finish: - * @connection: a #GSocketConnection - * @result: the #GAsyncResult - * @error: #GError for error reporting, or %NULL to ignore. - * - * Gets the result of a g_socket_connection_connect_async() call. - * - * Returns: %TRUE if the connection succeeded, %FALSE on error - * Since: 2.32 - */ - - -/** - * g_socket_connection_factory_create_connection: - * @socket: a #GSocket - * - * Creates a #GSocketConnection subclass of the right type for - * @socket. - * - * Returns: (transfer full): a #GSocketConnection - * Since: 2.22 - */ - - -/** - * g_socket_connection_factory_lookup_type: - * @family: a #GSocketFamily - * @type: a #GSocketType - * @protocol_id: a protocol id - * - * Looks up the #GType to be used when creating socket connections on - * sockets with the specified @family, @type and @protocol_id. - * - * If no type is registered, the #GSocketConnection base type is returned. - * - * Returns: a #GType - * Since: 2.22 - */ - - -/** - * g_socket_connection_factory_register_type: - * @g_type: a #GType, inheriting from %G_TYPE_SOCKET_CONNECTION - * @family: a #GSocketFamily - * @type: a #GSocketType - * @protocol: a protocol id - * - * Looks up the #GType to be used when creating socket connections on - * sockets with the specified @family, @type and @protocol. - * - * If no type is registered, the #GSocketConnection base type is returned. - * - * Since: 2.22 - */ - - -/** - * g_socket_connection_get_local_address: - * @connection: a #GSocketConnection - * @error: #GError for error reporting, or %NULL to ignore. - * - * Try to get the local address of a socket connection. - * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_socket_connection_get_remote_address: - * @connection: a #GSocketConnection - * @error: #GError for error reporting, or %NULL to ignore. - * - * Try to get the remote address of a socket connection. - * - * Since GLib 2.40, when used with g_socket_client_connect() or - * g_socket_client_connect_async(), during emission of - * %G_SOCKET_CLIENT_CONNECTING, this function will return the remote - * address that will be used for the connection. This allows - * applications to print e.g. "Connecting to example.com - * (10.42.77.3)...". - * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_socket_connection_get_socket: - * @connection: a #GSocketConnection - * - * Gets the underlying #GSocket object of the connection. - * This can be useful if you want to do something unusual on it - * not supported by the #GSocketConnection APIs. - * - * Returns: (transfer none): a #GSocket or %NULL on error. - * Since: 2.22 - */ - - -/** - * g_socket_connection_is_connected: - * @connection: a #GSocketConnection - * - * Checks if @connection is connected. This is equivalent to calling - * g_socket_is_connected() on @connection's underlying #GSocket. - * - * Returns: whether @connection is connected - * Since: 2.32 - */ - - -/** - * g_socket_control_message_deserialize: - * @level: a socket level - * @type: a socket control message type for the given @level - * @size: the size of the data in bytes - * @data: (array length=size) (element-type guint8): pointer to the message data - * - * Tries to deserialize a socket control message of a given - * @level and @type. This will ask all known (to GType) subclasses - * of #GSocketControlMessage if they can understand this kind - * of message and if so deserialize it into a #GSocketControlMessage. - * - * If there is no implementation for this kind of control message, %NULL - * will be returned. - * - * Returns: (transfer full): the deserialized message or %NULL - * Since: 2.22 - */ - - -/** - * g_socket_control_message_get_level: - * @message: a #GSocketControlMessage - * - * Returns the "level" (i.e. the originating protocol) of the control message. - * This is often SOL_SOCKET. - * - * Returns: an integer describing the level - * Since: 2.22 - */ - - -/** - * g_socket_control_message_get_msg_type: - * @message: a #GSocketControlMessage - * - * Returns the protocol specific type of the control message. - * For instance, for UNIX fd passing this would be SCM_RIGHTS. - * - * Returns: an integer describing the type of control message - * Since: 2.22 - */ - - -/** - * g_socket_control_message_get_size: - * @message: a #GSocketControlMessage - * - * Returns the space required for the control message, not including - * headers or alignment. - * - * Returns: The number of bytes required. - * Since: 2.22 - */ - - -/** - * g_socket_control_message_serialize: - * @message: a #GSocketControlMessage - * @data: (not nullable): A buffer to write data to - * - * Converts the data in the message to bytes placed in the - * message. - * - * @data is guaranteed to have enough space to fit the size - * returned by g_socket_control_message_get_size() on this - * object. - * - * Since: 2.22 - */ - - -/** - * g_socket_create_source: (skip) - * @socket: a #GSocket - * @condition: a #GIOCondition mask to monitor - * @cancellable: (nullable): a %GCancellable or %NULL - * - * Creates a #GSource that can be attached to a %GMainContext to monitor - * for the availability of the specified @condition on the socket. The #GSource - * keeps a reference to the @socket. - * - * The callback on the source is of the #GSocketSourceFunc type. - * - * It is meaningless to specify %G_IO_ERR or %G_IO_HUP in @condition; - * these conditions will always be reported output if they are true. - * - * @cancellable if not %NULL can be used to cancel the source, which will - * cause the source to trigger, reporting the current condition (which - * is likely 0 unless cancellation happened at the same time as a - * condition change). You can check for this in the callback using - * g_cancellable_is_cancelled(). - * - * If @socket has a timeout set, and it is reached before @condition - * occurs, the source will then trigger anyway, reporting %G_IO_IN or - * %G_IO_OUT depending on @condition. However, @socket will have been - * marked as having had a timeout, and so the next #GSocket I/O method - * you call will then fail with a %G_IO_ERROR_TIMED_OUT. - * - * Returns: (transfer full): a newly allocated %GSource, free with g_source_unref(). - * Since: 2.22 - */ - - -/** - * g_socket_get_available_bytes: - * @socket: a #GSocket - * - * Get the amount of data pending in the OS input buffer, without blocking. - * - * If @socket is a UDP or SCTP socket, this will return the size of - * just the next packet, even if additional packets are buffered after - * that one. - * - * Note that on Windows, this function is rather inefficient in the - * UDP case, and so if you know any plausible upper bound on the size - * of the incoming packet, it is better to just do a - * g_socket_receive() with a buffer of that size, rather than calling - * g_socket_get_available_bytes() first and then doing a receive of - * exactly the right size. - * - * Returns: the number of bytes that can be read from the socket - * without blocking or truncating, or -1 on error. - * Since: 2.32 - */ - - -/** - * g_socket_get_blocking: - * @socket: a #GSocket. - * - * Gets the blocking mode of the socket. For details on blocking I/O, - * see g_socket_set_blocking(). - * - * Returns: %TRUE if blocking I/O is used, %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_socket_get_broadcast: - * @socket: a #GSocket. - * - * Gets the broadcast setting on @socket; if %TRUE, - * it is possible to send packets to broadcast - * addresses. - * - * Returns: the broadcast setting on @socket - * Since: 2.32 - */ - - -/** - * g_socket_get_credentials: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Returns the credentials of the foreign process connected to this - * socket, if any (e.g. it is only supported for %G_SOCKET_FAMILY_UNIX - * sockets). - * - * If this operation isn't supported on the OS, the method fails with - * the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented - * by reading the %SO_PEERCRED option on the underlying socket. - * - * This method can be expected to be available on the following platforms: - * - * - Linux since GLib 2.26 - * - OpenBSD since GLib 2.30 - * - Solaris, Illumos and OpenSolaris since GLib 2.40 - * - NetBSD since GLib 2.42 - * - macOS, tvOS, iOS since GLib 2.66 - * - * Other ways to obtain credentials from a foreign peer includes the - * #GUnixCredentialsMessage type and - * g_unix_connection_send_credentials() / - * g_unix_connection_receive_credentials() functions. - * - * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object - * that must be freed with g_object_unref(). - * Since: 2.26 - */ - - -/** - * g_socket_get_family: - * @socket: a #GSocket. - * - * Gets the socket family of the socket. - * - * Returns: a #GSocketFamily - * Since: 2.22 - */ - - -/** - * g_socket_get_fd: - * @socket: a #GSocket. - * - * Returns the underlying OS socket object. On unix this - * is a socket file descriptor, and on Windows this is - * a Winsock2 SOCKET handle. This may be useful for - * doing platform specific or otherwise unusual operations - * on the socket. - * - * Returns: the file descriptor of the socket. - * Since: 2.22 - */ - - -/** - * g_socket_get_keepalive: - * @socket: a #GSocket. - * - * Gets the keepalive mode of the socket. For details on this, - * see g_socket_set_keepalive(). - * - * Returns: %TRUE if keepalive is active, %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_socket_get_listen_backlog: - * @socket: a #GSocket. - * - * Gets the listen backlog setting of the socket. For details on this, - * see g_socket_set_listen_backlog(). - * - * Returns: the maximum number of pending connections. - * Since: 2.22 - */ - - -/** - * g_socket_get_local_address: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Try to get the local address of a bound socket. This is only - * useful if the socket has been bound to a local address, - * either explicitly or implicitly when connecting. - * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_socket_get_multicast_loopback: - * @socket: a #GSocket. - * - * Gets the multicast loopback setting on @socket; if %TRUE (the - * default), outgoing multicast packets will be looped back to - * multicast listeners on the same host. - * - * Returns: the multicast loopback setting on @socket - * Since: 2.32 - */ - - -/** - * g_socket_get_multicast_ttl: - * @socket: a #GSocket. - * - * Gets the multicast time-to-live setting on @socket; see - * g_socket_set_multicast_ttl() for more details. - * - * Returns: the multicast time-to-live setting on @socket - * Since: 2.32 - */ - - -/** - * g_socket_get_option: - * @socket: a #GSocket - * @level: the "API level" of the option (eg, `SOL_SOCKET`) - * @optname: the "name" of the option (eg, `SO_BROADCAST`) - * @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 - * getsockopt(). (If you need to fetch a non-integer-valued option, - * you will need to call getsockopt() directly.) - * - * The [][gio-gnetworking.h] - * 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 (`errno` or WSAGetLastError()) will still - * be set to the result of the getsockopt() call. - * Since: 2.36 - */ - - -/** - * g_socket_get_protocol: - * @socket: a #GSocket. - * - * Gets the socket protocol id the socket was created with. - * In case the protocol is unknown, -1 is returned. - * - * Returns: a protocol id, or -1 if unknown - * Since: 2.22 - */ - - -/** - * g_socket_get_remote_address: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Try to get the remote address of a connected socket. This is only - * useful for connection oriented sockets that have been connected. - * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_socket_get_socket_type: - * @socket: a #GSocket. - * - * Gets the socket type of the socket. - * - * Returns: a #GSocketType - * Since: 2.22 - */ - - -/** - * g_socket_get_timeout: - * @socket: a #GSocket. - * - * Gets the timeout setting of the socket. For details on this, see - * g_socket_set_timeout(). - * - * Returns: the timeout in seconds - * Since: 2.26 - */ - - -/** - * g_socket_get_ttl: - * @socket: a #GSocket. - * - * Gets the unicast time-to-live setting on @socket; see - * g_socket_set_ttl() for more details. - * - * Returns: the time-to-live setting on @socket - * Since: 2.32 - */ - - -/** - * g_socket_is_closed: - * @socket: a #GSocket - * - * Checks whether a socket is closed. - * - * Returns: %TRUE if socket is closed, %FALSE otherwise - * Since: 2.22 - */ - - -/** - * g_socket_is_connected: - * @socket: a #GSocket. - * - * Check whether the socket is connected. This is only useful for - * connection-oriented sockets. - * - * If using g_socket_shutdown(), this function will return %TRUE until the - * socket has been shut down for reading and writing. If you do a non-blocking - * connect, this function will not return %TRUE until after you call - * g_socket_check_connect_result(). - * - * Returns: %TRUE if socket is connected, %FALSE otherwise. - * Since: 2.22 - */ - - -/** - * g_socket_join_multicast_group: - * @socket: a #GSocket. - * @group: a #GInetAddress specifying the group address to join. - * @iface: (nullable): Name of the interface to use, or %NULL - * @source_specific: %TRUE if source-specific multicast should be used - * @error: #GError for error reporting, or %NULL to ignore. - * - * Registers @socket to receive multicast messages sent to @group. - * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have - * been bound to an appropriate interface and port with - * g_socket_bind(). - * - * If @iface is %NULL, the system will automatically pick an interface - * to bind to based on @group. - * - * If @source_specific is %TRUE, source-specific multicast as defined - * in RFC 4604 is used. Note that on older platforms this may fail - * with a %G_IO_ERROR_NOT_SUPPORTED error. - * - * To bind to a given source-specific multicast address, use - * g_socket_join_multicast_group_ssm() instead. - * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.32 - */ - - -/** - * g_socket_join_multicast_group_ssm: - * @socket: a #GSocket. - * @group: a #GInetAddress specifying the group address to join. - * @source_specific: (nullable): a #GInetAddress specifying the - * source-specific multicast address or %NULL to ignore. - * @iface: (nullable): Name of the interface to use, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Registers @socket to receive multicast messages sent to @group. - * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have - * been bound to an appropriate interface and port with - * g_socket_bind(). - * - * If @iface is %NULL, the system will automatically pick an interface - * to bind to based on @group. - * - * If @source_specific is not %NULL, use source-specific multicast as - * defined in RFC 4604. Note that on older platforms this may fail - * with a %G_IO_ERROR_NOT_SUPPORTED error. - * - * Note that this function can be called multiple times for the same - * @group with different @source_specific in order to receive multicast - * packets from more than one source. - * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.56 - */ - - -/** - * g_socket_leave_multicast_group: - * @socket: a #GSocket. - * @group: a #GInetAddress specifying the group address to leave. - * @iface: (nullable): Interface used - * @source_specific: %TRUE if source-specific multicast was used - * @error: #GError for error reporting, or %NULL to ignore. - * - * Removes @socket from the multicast group defined by @group, @iface, - * and @source_specific (which must all have the same values they had - * when you joined the group). - * - * @socket remains bound to its address and port, and can still receive - * unicast messages after calling this. - * - * To unbind to a given source-specific multicast address, use - * g_socket_leave_multicast_group_ssm() instead. - * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.32 - */ - - -/** - * g_socket_leave_multicast_group_ssm: - * @socket: a #GSocket. - * @group: a #GInetAddress specifying the group address to leave. - * @source_specific: (nullable): a #GInetAddress specifying the - * source-specific multicast address or %NULL to ignore. - * @iface: (nullable): Name of the interface to use, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Removes @socket from the multicast group defined by @group, @iface, - * and @source_specific (which must all have the same values they had - * when you joined the group). - * - * @socket remains bound to its address and port, and can still receive - * unicast messages after calling this. - * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.56 - */ - - -/** - * g_socket_listen: - * @socket: a #GSocket. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Marks the socket as a server socket, i.e. a socket that is used - * to accept incoming requests using g_socket_accept(). - * - * Before calling this the socket must be bound to a local address using - * g_socket_bind(). - * - * To set the maximum amount of outstanding clients, use - * g_socket_set_listen_backlog(). - * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 - */ - - -/** - * g_socket_listener_accept: - * @listener: a #GSocketListener - * @source_object: (out) (transfer none) (optional) (nullable): location where #GObject pointer will be stored, or %NULL - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Blocks waiting for a client to connect to any of the sockets added - * to the listener. Returns a #GSocketConnection for the socket that was - * accepted. - * - * If @source_object is not %NULL it will be filled out with the source - * object specified when the corresponding socket or address was added - * to the listener. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 - */ - - -/** - * g_socket_listener_accept_async: - * @listener: a #GSocketListener - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback - * - * This is the asynchronous version of g_socket_listener_accept(). - * - * When the operation is finished @callback will be - * called. You can then call g_socket_listener_accept_finish() - * to get the result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_socket_listener_accept_finish: - * @listener: a #GSocketListener - * @result: a #GAsyncResult. - * @source_object: (out) (transfer none) (optional) (nullable): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes an async accept operation. See g_socket_listener_accept_async() - * - * Returns: (transfer full): a #GSocketConnection on success, %NULL on error. - * Since: 2.22 - */ - - -/** - * g_socket_listener_accept_socket: - * @listener: a #GSocketListener - * @source_object: (out) (transfer none) (optional) (nullable): location where #GObject pointer will be stored, or %NULL. - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Blocks waiting for a client to connect to any of the sockets added - * to the listener. Returns the #GSocket that was accepted. - * - * If you want to accept the high-level #GSocketConnection, not a #GSocket, - * which is often the case, then you should use g_socket_listener_accept() - * instead. - * - * If @source_object is not %NULL it will be filled out with the source - * object specified when the corresponding socket or address was added - * to the listener. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * Returns: (transfer full): a #GSocket on success, %NULL on error. - * Since: 2.22 - */ - - -/** - * g_socket_listener_accept_socket_async: - * @listener: a #GSocketListener - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback - * @user_data: (closure): user data for the callback - * - * This is the asynchronous version of g_socket_listener_accept_socket(). - * - * When the operation is finished @callback will be - * called. You can then call g_socket_listener_accept_socket_finish() - * to get the result of the operation. - * - * Since: 2.22 - */ - - -/** - * g_socket_listener_accept_socket_finish: - * @listener: a #GSocketListener - * @result: a #GAsyncResult. - * @source_object: (out) (transfer none) (optional) (nullable): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Finishes an async accept operation. See g_socket_listener_accept_socket_async() - * - * Returns: (transfer full): a #GSocket on success, %NULL on error. - * Since: 2.22 - */ - - -/** - * g_socket_listener_add_address: - * @listener: a #GSocketListener - * @address: a #GSocketAddress - * @type: a #GSocketType - * @protocol: a #GSocketProtocol - * @source_object: (nullable): Optional #GObject identifying this source - * @effective_address: (out) (optional): location to store the address that was bound to, or %NULL. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a socket of type @type and protocol @protocol, binds - * it to @address and adds it to the set of sockets we're accepting - * sockets from. - * - * Note that adding an IPv6 address, depending on the platform, - * may or may not result in a listener that also accepts IPv4 - * connections. For more deterministic behavior, see - * g_socket_listener_add_inet_port(). - * - * @source_object will be passed out in the various calls - * to accept to identify this particular source, which is - * useful if you're listening on multiple addresses and do - * different things depending on what address is connected to. - * - * If successful and @effective_address is non-%NULL then it will - * be set to the address that the binding actually occurred at. This - * is helpful for determining the port number that was used for when - * requesting a binding to port 0 (ie: "any port"). This address, if - * requested, belongs to the caller and must be freed. - * - * Call g_socket_listener_close() to stop listening on @address; this will not - * be done automatically when you drop your final reference to @listener, as - * references may be held internally. - * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 - */ - - -/** - * g_socket_listener_add_any_inet_port: - * @listener: a #GSocketListener - * @source_object: (nullable): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to - * ignore. - * - * Listens for TCP connections on any available port number for both - * IPv6 and IPv4 (if each is available). - * - * This is useful if you need to have a socket for incoming connections - * but don't care about the specific port number. - * - * @source_object will be passed out in the various calls - * to accept to identify this particular source, which is - * useful if you're listening on multiple addresses and do - * different things depending on what address is connected to. - * - * Returns: the port number, or 0 in case of failure. - * Since: 2.24 - */ - - -/** - * g_socket_listener_add_inet_port: - * @listener: a #GSocketListener - * @port: an IP port number (non-zero) - * @source_object: (nullable): Optional #GObject identifying this source - * @error: #GError for error reporting, or %NULL to ignore. - * - * Helper function for g_socket_listener_add_address() that - * creates a TCP/IP socket listening on IPv4 and IPv6 (if - * supported) on the specified port on all interfaces. - * - * @source_object will be passed out in the various calls - * to accept to identify this particular source, which is - * useful if you're listening on multiple addresses and do - * different things depending on what address is connected to. - * - * Call g_socket_listener_close() to stop listening on @port; this will not - * be done automatically when you drop your final reference to @listener, as - * references may be held internally. - * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 - */ - - -/** - * g_socket_listener_add_socket: - * @listener: a #GSocketListener - * @socket: a listening #GSocket - * @source_object: (nullable): Optional #GObject identifying this source - * @error: #GError for error reporting, or %NULL to ignore. - * - * Adds @socket to the set of sockets that we try to accept - * new clients from. The socket must be bound to a local - * address and listened to. - * - * @source_object will be passed out in the various calls - * to accept to identify this particular source, which is - * useful if you're listening on multiple addresses and do - * different things depending on what address is connected to. - * - * The @socket will not be automatically closed when the @listener is finalized - * unless the listener held the final reference to the socket. Before GLib 2.42, - * the @socket was automatically closed on finalization of the @listener, even - * if references to it were held elsewhere. - * - * Returns: %TRUE on success, %FALSE on error. - * Since: 2.22 - */ - - -/** - * g_socket_listener_close: - * @listener: a #GSocketListener - * - * Closes all the sockets in the listener. - * - * Since: 2.22 - */ - - -/** - * g_socket_listener_new: - * - * Creates a new #GSocketListener with no sockets to listen for. - * New listeners can be added with e.g. g_socket_listener_add_address() - * or g_socket_listener_add_inet_port(). - * - * Returns: a new #GSocketListener. - * Since: 2.22 - */ - - -/** - * g_socket_listener_set_backlog: - * @listener: a #GSocketListener - * @listen_backlog: an integer - * - * Sets the listen backlog on the sockets in the listener. This must be called - * before adding any sockets, addresses or ports to the #GSocketListener (for - * example, by calling g_socket_listener_add_inet_port()) to be effective. - * - * See g_socket_set_listen_backlog() for details - * - * Since: 2.22 - */ - - -/** - * g_socket_new: - * @family: the socket family to use, e.g. %G_SOCKET_FAMILY_IPV4. - * @type: the socket type to use. - * @protocol: the id of the protocol to use, or 0 for default. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a new #GSocket with the defined family, type and protocol. - * If @protocol is 0 (%G_SOCKET_PROTOCOL_DEFAULT) the default protocol type - * for the family and type is used. - * - * The @protocol is a family and type specific int that specifies what - * kind of protocol to use. #GSocketProtocol lists several common ones. - * Many families only support one protocol, and use 0 for this, others - * support several and using 0 means to use the default protocol for - * the family and type. - * - * The protocol id is passed directly to the operating - * system, so you can use protocols not listed in #GSocketProtocol if you - * know the protocol number used for it. - * - * Returns: a #GSocket or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_socket_new_from_fd: - * @fd: a native socket file descriptor. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a new #GSocket from a native file descriptor - * or winsock SOCKET handle. - * - * This reads all the settings from the file descriptor so that - * all properties should work. Note that the file descriptor - * will be set to non-blocking mode, independent on the blocking - * mode of the #GSocket. - * - * On success, the returned #GSocket takes ownership of @fd. On failure, the - * caller must close @fd themselves. - * - * Since GLib 2.46, it is no longer a fatal error to call this on a non-socket - * descriptor. Instead, a GError will be set with code %G_IO_ERROR_FAILED - * - * Returns: a #GSocket or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.22 - */ - - -/** - * g_socket_receive: - * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8) (out caller-allocates): - * 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: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Receive data (up to @size bytes) from a socket. This is mainly used by - * connection-oriented sockets; it is identical to g_socket_receive_from() - * with @address set to %NULL. - * - * For %G_SOCKET_TYPE_DATAGRAM and %G_SOCKET_TYPE_SEQPACKET sockets, - * g_socket_receive() will always read either 0 or 1 complete messages from - * the socket. If the received message is too large to fit in @buffer, then - * the data beyond @size bytes will be discarded, without any explicit - * indication that this has occurred. - * - * For %G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any - * number of bytes, up to @size. If more than @size bytes have been - * received, the additional data will be returned in future calls to - * g_socket_receive(). - * - * If the socket is in blocking mode the call will block until there - * is some data to receive, the connection is closed, or there is an - * error. If there is no data available and the socket is in - * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be - * returned. To be notified when data is available, wait for the - * %G_IO_IN condition. - * - * On error -1 is returned and @error is set accordingly. - * - * Returns: Number of bytes read, or 0 if the connection was closed by - * the peer, or -1 on error - * Since: 2.22 - */ - - -/** - * g_socket_receive_from: - * @socket: a #GSocket - * @address: (out) (optional): a pointer to a #GSocketAddress - * pointer, or %NULL - * @buffer: (array length=size) (element-type guint8) (out caller-allocates): - * 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: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Receive data (up to @size bytes) from a socket. - * - * If @address is non-%NULL then @address will be set equal to the - * source address of the received packet. - * @address is owned by the caller. - * - * See g_socket_receive() for additional information. - * - * Returns: Number of bytes read, or 0 if the connection was closed by - * the peer, or -1 on error - * Since: 2.22 - */ - - -/** - * g_socket_receive_message: - * @socket: a #GSocket - * @address: (out) (optional): a pointer to a #GSocketAddress - * pointer, or %NULL - * @vectors: (array length=num_vectors): an array of #GInputVector structs - * @num_vectors: the number of elements in @vectors, or -1 - * @messages: (array length=num_messages) (out) (optional) (nullable): a pointer - * which may be filled with an array of #GSocketControlMessages, or %NULL - * @num_messages: (out): a pointer which will be filled with the number of - * elements in @messages, or %NULL - * @flags: (inout): a pointer to an int containing #GSocketMsgFlags flags, - * which may additionally contain - * [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) - * @cancellable: a %GCancellable or %NULL - * @error: a #GError pointer, or %NULL - * - * Receive data from a socket. For receiving multiple messages, see - * g_socket_receive_messages(); for easier use, see - * g_socket_receive() and g_socket_receive_from(). - * - * If @address is non-%NULL then @address will be set equal to the - * source address of the received packet. - * @address is owned by the caller. - * - * @vector must point to an array of #GInputVector structs and - * @num_vectors must be the length of this array. These structs - * describe the buffers that received data will be scattered into. - * If @num_vectors is -1, then @vectors is assumed to be terminated - * by a #GInputVector with a %NULL buffer pointer. - * - * As a special case, if @num_vectors is 0 (in which case, @vectors - * may of course be %NULL), then a single byte is received and - * discarded. This is to facilitate the common practice of sending a - * single '\0' byte for the purposes of transferring ancillary data. - * - * @messages, if non-%NULL, will be set to point to a newly-allocated - * array of #GSocketControlMessage instances or %NULL if no such - * messages was received. These correspond to the control messages - * received from the kernel, one #GSocketControlMessage per message - * from the kernel. This array is %NULL-terminated and must be freed - * by the caller using g_free() after calling g_object_unref() on each - * element. If @messages is %NULL, any control messages received will - * be discarded. - * - * @num_messages, if non-%NULL, will be set to the number of control - * messages received. - * - * If both @messages and @num_messages are non-%NULL, then - * @num_messages gives the number of #GSocketControlMessage instances - * in @messages (ie: not including the %NULL terminator). - * - * @flags is an in/out parameter. The commonly available arguments - * for this are available in the #GSocketMsgFlags enum, but the - * values there are the same as the system values, and the flags - * are passed in as-is, so you can pass in system-specific flags too - * (and g_socket_receive_message() may pass system-specific flags out). - * Flags passed in to the parameter affect the receive operation; flags returned - * out of it are relevant to the specific returned message. - * - * As with g_socket_receive(), data may be discarded if @socket is - * %G_SOCKET_TYPE_DATAGRAM or %G_SOCKET_TYPE_SEQPACKET and you do not - * provide enough buffer space to read a complete message. You can pass - * %G_SOCKET_MSG_PEEK in @flags to peek at the current message without - * removing it from the receive queue, but there is no portable way to find - * out the length of the message other than by reading it into a - * sufficiently-large buffer. - * - * If the socket is in blocking mode the call will block until there - * is some data to receive, the connection is closed, or there is an - * error. If there is no data available and the socket is in - * non-blocking mode, a %G_IO_ERROR_WOULD_BLOCK error will be - * returned. To be notified when data is available, wait for the - * %G_IO_IN condition. - * - * On error -1 is returned and @error is set accordingly. - * - * Returns: Number of bytes read, or 0 if the connection was closed by - * the peer, or -1 on error - * Since: 2.22 - */ - - -/** - * g_socket_receive_messages: - * @socket: a #GSocket - * @messages: (array length=num_messages): an array of #GInputMessage structs - * @num_messages: the number of elements in @messages - * @flags: an int containing #GSocketMsgFlags flags for the overall operation, - * which may additionally contain - * [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore - * - * Receive multiple data messages from @socket in one go. This is the most - * complicated and fully-featured version of this call. For easier use, see - * g_socket_receive(), g_socket_receive_from(), and g_socket_receive_message(). - * - * @messages must point to an array of #GInputMessage structs and - * @num_messages must be the length of this array. Each #GInputMessage - * contains a pointer to an array of #GInputVector structs describing the - * buffers that the data received in each message will be written to. Using - * multiple #GInputVectors is more memory-efficient than manually copying data - * out of a single buffer to multiple sources, and more system-call-efficient - * than making multiple calls to g_socket_receive(), such as in scenarios where - * a lot of data packets need to be received (e.g. high-bandwidth video - * streaming over RTP/UDP). - * - * @flags modify how all messages are received. The commonly available - * arguments for this are available in the #GSocketMsgFlags enum, but the - * values there are the same as the system values, and the flags - * are passed in as-is, so you can pass in system-specific flags too. These - * flags affect the overall receive operation. Flags affecting individual - * messages are returned in #GInputMessage.flags. - * - * The other members of #GInputMessage are treated as described in its - * documentation. - * - * If #GSocket:blocking is %TRUE the call will block until @num_messages have - * been received, or the end of the stream is reached. - * - * If #GSocket:blocking is %FALSE the call will return up to @num_messages - * without blocking, or %G_IO_ERROR_WOULD_BLOCK if no messages are queued in the - * operating system to be received. - * - * In blocking mode, if #GSocket:timeout is positive and is reached before any - * messages are received, %G_IO_ERROR_TIMED_OUT is returned, otherwise up to - * @num_messages are returned. (Note: This is effectively the - * behaviour of `MSG_WAITFORONE` with recvmmsg().) - * - * To be notified when messages are available, wait for the - * %G_IO_IN condition. Note though that you may still receive - * %G_IO_ERROR_WOULD_BLOCK from g_socket_receive_messages() even if you were - * previously notified of a %G_IO_IN condition. - * - * If the remote peer closes the connection, any messages queued in the - * operating system will be returned, and subsequent calls to - * g_socket_receive_messages() will return 0 (with no error set). - * - * On error -1 is returned and @error is set accordingly. An error will only - * be returned if zero messages could be received; otherwise the number of - * messages successfully received before the error will be returned. - * - * Returns: number of messages received, or -1 on error. Note that the number - * of messages received may be smaller than @num_messages if in non-blocking - * mode, if the peer closed the connection, or if @num_messages - * was larger than `UIO_MAXIOV` (1024), in which case the caller may re-try - * to receive the remaining messages. - * Since: 2.48 - */ - - -/** - * g_socket_receive_with_blocking: - * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8) (out caller-allocates): - * 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: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * This behaves exactly the same as g_socket_receive(), except that - * the choice of blocking or non-blocking behavior is determined by - * the @blocking argument rather than by @socket's properties. - * - * Returns: Number of bytes read, or 0 if the connection was closed by - * the peer, or -1 on error - * Since: 2.26 - */ - - -/** - * g_socket_send: - * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): the buffer - * containing the data to send. - * @size: the number of bytes to send - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Tries to send @size bytes from @buffer on the socket. This is - * mainly used by connection-oriented sockets; it is identical to - * g_socket_send_to() with @address set to %NULL. - * - * If the socket is in blocking mode the call will block until there is - * space for the data in the socket queue. If there is no space available - * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error - * will be returned. To be notified when space is available, wait for the - * %G_IO_OUT condition. Note though that you may still receive - * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously - * notified of a %G_IO_OUT condition. (On Windows in particular, this is - * very common due to the way the underlying APIs work.) - * - * On error -1 is returned and @error is set accordingly. - * - * Returns: Number of bytes written (which may be less than @size), or -1 - * on error - * Since: 2.22 - */ - - -/** - * g_socket_send_message: - * @socket: a #GSocket - * @address: (nullable): a #GSocketAddress, or %NULL - * @vectors: (array length=num_vectors): an array of #GOutputVector structs - * @num_vectors: the number of elements in @vectors, or -1 - * @messages: (array length=num_messages) (nullable): a pointer to an - * array of #GSocketControlMessages, or %NULL. - * @num_messages: number of elements in @messages, or -1. - * @flags: an int containing #GSocketMsgFlags flags, which may additionally - * contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Send data to @address on @socket. For sending multiple messages see - * g_socket_send_messages(); for easier use, see - * g_socket_send() and g_socket_send_to(). - * - * If @address is %NULL then the message is sent to the default receiver - * (set by g_socket_connect()). - * - * @vectors must point to an array of #GOutputVector structs and - * @num_vectors must be the length of this array. (If @num_vectors is -1, - * then @vectors is assumed to be terminated by a #GOutputVector with a - * %NULL buffer pointer.) The #GOutputVector structs describe the buffers - * that the sent data will be gathered from. Using multiple - * #GOutputVectors is more memory-efficient than manually copying - * data from multiple sources into a single buffer, and more - * network-efficient than making multiple calls to g_socket_send(). - * - * @messages, if non-%NULL, is taken to point to an array of @num_messages - * #GSocketControlMessage instances. These correspond to the control - * messages to be sent on the socket. - * If @num_messages is -1 then @messages is treated as a %NULL-terminated - * array. - * - * @flags modify how the message is sent. The commonly available arguments - * for this are available in the #GSocketMsgFlags enum, but the - * values there are the same as the system values, and the flags - * are passed in as-is, so you can pass in system-specific flags too. - * - * If the socket is in blocking mode the call will block until there is - * space for the data in the socket queue. If there is no space available - * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error - * will be returned. To be notified when space is available, wait for the - * %G_IO_OUT condition. Note though that you may still receive - * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously - * notified of a %G_IO_OUT condition. (On Windows in particular, this is - * very common due to the way the underlying APIs work.) - * - * The sum of the sizes of each #GOutputVector in vectors must not be - * greater than %G_MAXSSIZE. If the message can be larger than this, - * then it is mandatory to use the g_socket_send_message_with_timeout() - * function. - * - * On error -1 is returned and @error is set accordingly. - * - * Returns: Number of bytes written (which may be less than @size), or -1 - * on error - * Since: 2.22 - */ - - -/** - * g_socket_send_message_with_timeout: - * @socket: a #GSocket - * @address: (nullable): a #GSocketAddress, or %NULL - * @vectors: (array length=num_vectors): an array of #GOutputVector structs - * @num_vectors: the number of elements in @vectors, or -1 - * @messages: (array length=num_messages) (nullable): a pointer to an - * array of #GSocketControlMessages, or %NULL. - * @num_messages: number of elements in @messages, or -1. - * @flags: an int containing #GSocketMsgFlags flags, which may additionally - * contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) - * @timeout_us: the maximum time (in microseconds) to wait, or -1 - * @bytes_written: (out) (optional): location to store the number of bytes that were written to the socket - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * This behaves exactly the same as g_socket_send_message(), except that - * the choice of timeout behavior is determined by the @timeout_us argument - * rather than by @socket's properties. - * - * On error %G_POLLABLE_RETURN_FAILED is returned and @error is set accordingly, or - * if the socket is currently not writable %G_POLLABLE_RETURN_WOULD_BLOCK is - * returned. @bytes_written will contain 0 in both cases. - * - * Returns: %G_POLLABLE_RETURN_OK if all data was successfully written, - * %G_POLLABLE_RETURN_WOULD_BLOCK if the socket is currently not writable, or - * %G_POLLABLE_RETURN_FAILED if an error happened and @error is set. - * Since: 2.60 - */ - - -/** - * g_socket_send_messages: - * @socket: a #GSocket - * @messages: (array length=num_messages): an array of #GOutputMessage structs - * @num_messages: the number of elements in @messages - * @flags: an int containing #GSocketMsgFlags flags, which may additionally - * contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html) - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Send multiple data messages from @socket in one go. This is the most - * complicated and fully-featured version of this call. For easier use, see - * g_socket_send(), g_socket_send_to(), and g_socket_send_message(). - * - * @messages must point to an array of #GOutputMessage structs and - * @num_messages must be the length of this array. Each #GOutputMessage - * contains an address to send the data to, and a pointer to an array of - * #GOutputVector structs to describe the buffers that the data to be sent - * for each message will be gathered from. Using multiple #GOutputVectors is - * more memory-efficient than manually copying data from multiple sources - * into a single buffer, and more network-efficient than making multiple - * calls to g_socket_send(). Sending multiple messages in one go avoids the - * overhead of making a lot of syscalls in scenarios where a lot of data - * packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP), - * or where the same data needs to be sent to multiple recipients. - * - * @flags modify how the message is sent. The commonly available arguments - * for this are available in the #GSocketMsgFlags enum, but the - * values there are the same as the system values, and the flags - * are passed in as-is, so you can pass in system-specific flags too. - * - * If the socket is in blocking mode the call will block until there is - * space for all the data in the socket queue. If there is no space available - * and the socket is in non-blocking mode a %G_IO_ERROR_WOULD_BLOCK error - * will be returned if no data was written at all, otherwise the number of - * messages sent will be returned. To be notified when space is available, - * wait for the %G_IO_OUT condition. Note though that you may still receive - * %G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously - * notified of a %G_IO_OUT condition. (On Windows in particular, this is - * very common due to the way the underlying APIs work.) - * - * On error -1 is returned and @error is set accordingly. An error will only - * be returned if zero messages could be sent; otherwise the number of messages - * successfully sent before the error will be returned. - * - * Returns: number of messages sent, or -1 on error. Note that the number of - * messages sent may be smaller than @num_messages if the socket is - * non-blocking or if @num_messages was larger than UIO_MAXIOV (1024), - * in which case the caller may re-try to send the remaining messages. - * Since: 2.44 - */ - - -/** - * g_socket_send_to: - * @socket: a #GSocket - * @address: (nullable): a #GSocketAddress, or %NULL - * @buffer: (array length=size) (element-type guint8): the buffer - * containing the data to send. - * @size: the number of bytes to send - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Tries to send @size bytes from @buffer to @address. If @address is - * %NULL then the message is sent to the default receiver (set by - * g_socket_connect()). - * - * See g_socket_send() for additional information. - * - * Returns: Number of bytes written (which may be less than @size), or -1 - * on error - * Since: 2.22 - */ - - -/** - * g_socket_send_with_blocking: - * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): the buffer - * containing the data to send. - * @size: the number of bytes to send - * @blocking: whether to do blocking or non-blocking I/O - * @cancellable: (nullable): a %GCancellable or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * This behaves exactly the same as g_socket_send(), except that - * the choice of blocking or non-blocking behavior is determined by - * the @blocking argument rather than by @socket's properties. - * - * Returns: Number of bytes written (which may be less than @size), or -1 - * on error - * Since: 2.26 - */ - - -/** - * g_socket_service_is_active: - * @service: a #GSocketService - * - * Check whether the service is active or not. An active - * service will accept new clients that connect, while - * a non-active service will let connecting clients queue - * up until the service is started. - * - * Returns: %TRUE if the service is active, %FALSE otherwise - * Since: 2.22 - */ - - -/** - * g_socket_service_new: - * - * Creates a new #GSocketService with no sockets to listen for. - * New listeners can be added with e.g. g_socket_listener_add_address() - * or g_socket_listener_add_inet_port(). - * - * New services are created active, there is no need to call - * g_socket_service_start(), unless g_socket_service_stop() has been - * called before. - * - * Returns: a new #GSocketService. - * Since: 2.22 - */ - - -/** - * g_socket_service_start: - * @service: a #GSocketService - * - * Restarts the service, i.e. start accepting connections - * from the added sockets when the mainloop runs. This only needs - * to be called after the service has been stopped from - * g_socket_service_stop(). - * - * This call is thread-safe, so it may be called from a thread - * handling an incoming client request. - * - * Since: 2.22 - */ - - -/** - * g_socket_service_stop: - * @service: a #GSocketService - * - * Stops the service, i.e. stops accepting connections - * from the added sockets when the mainloop runs. - * - * This call is thread-safe, so it may be called from a thread - * handling an incoming client request. - * - * Note that this only stops accepting new connections; it does not - * close the listening sockets, and you can call - * g_socket_service_start() again later to begin listening again. To - * close the listening sockets, call g_socket_listener_close(). (This - * will happen automatically when the #GSocketService is finalized.) - * - * This must be called before calling g_socket_listener_close() as - * the socket service will start accepting connections immediately - * when a new socket is added. - * - * Since: 2.22 - */ - - -/** - * g_socket_set_blocking: - * @socket: a #GSocket. - * @blocking: Whether to use blocking I/O or not. - * - * Sets the blocking mode of the socket. In blocking mode - * all operations (which don’t take an explicit blocking parameter) block until - * they succeed or there is an error. In - * non-blocking mode all functions return results immediately or - * with a %G_IO_ERROR_WOULD_BLOCK error. - * - * All sockets are created in blocking mode. However, note that the - * platform level socket is always non-blocking, and blocking mode - * is a GSocket level feature. - * - * Since: 2.22 - */ - - -/** - * g_socket_set_broadcast: - * @socket: a #GSocket. - * @broadcast: whether @socket should allow sending to broadcast - * addresses - * - * Sets whether @socket should allow sending to broadcast addresses. - * This is %FALSE by default. - * - * Since: 2.32 - */ - - -/** - * g_socket_set_keepalive: - * @socket: a #GSocket. - * @keepalive: Value for the keepalive flag - * - * Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When - * this flag is set on a socket, the system will attempt to verify that the - * remote socket endpoint is still present if a sufficiently long period of - * time passes with no data being exchanged. If the system is unable to - * verify the presence of the remote endpoint, it will automatically close - * the connection. - * - * This option is only functional on certain kinds of sockets. (Notably, - * %G_SOCKET_PROTOCOL_TCP sockets.) - * - * The exact time between pings is system- and protocol-dependent, but will - * normally be at least two hours. Most commonly, you would set this flag - * on a server socket if you want to allow clients to remain idle for long - * periods of time, but also want to ensure that connections are eventually - * garbage-collected if clients crash or become unreachable. - * - * Since: 2.22 - */ - - -/** - * g_socket_set_listen_backlog: - * @socket: a #GSocket. - * @backlog: the maximum number of pending connections. - * - * Sets the maximum number of outstanding connections allowed - * when listening on this socket. If more clients than this are - * connecting to the socket and the application is not handling them - * on time then the new connections will be refused. - * - * Note that this must be called before g_socket_listen() and has no - * effect if called after that. - * - * Since: 2.22 - */ - - -/** - * g_socket_set_multicast_loopback: - * @socket: a #GSocket. - * @loopback: whether @socket should receive messages sent to its - * multicast groups from the local host - * - * Sets whether outgoing multicast packets will be received by sockets - * listening on that multicast address on the same host. This is %TRUE - * by default. - * - * Since: 2.32 - */ - - -/** - * g_socket_set_multicast_ttl: - * @socket: a #GSocket. - * @ttl: the time-to-live value for all multicast datagrams on @socket - * - * Sets the time-to-live for outgoing multicast datagrams on @socket. - * By default, this is 1, meaning that multicast packets will not leave - * the local network. - * - * Since: 2.32 - */ - - -/** - * g_socket_set_option: - * @socket: a #GSocket - * @level: the "API level" of the option (eg, `SOL_SOCKET`) - * @optname: the "name" of the option (eg, `SO_BROADCAST`) - * @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 - * setsockopt(). (If you need to set a non-integer-valued option, - * you will need to call setsockopt() directly.) - * - * The [][gio-gnetworking.h] - * 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 (`errno` or WSAGetLastError()) will still - * be set to the result of the setsockopt() call. - * Since: 2.36 - */ - - -/** - * g_socket_set_timeout: - * @socket: a #GSocket. - * @timeout: the timeout for @socket, in seconds, or 0 for none - * - * Sets the time in seconds after which I/O operations on @socket will - * time out if they have not yet completed. - * - * On a blocking socket, this means that any blocking #GSocket - * operation will time out after @timeout seconds of inactivity, - * returning %G_IO_ERROR_TIMED_OUT. - * - * On a non-blocking socket, calls to g_socket_condition_wait() will - * also fail with %G_IO_ERROR_TIMED_OUT after the given time. Sources - * created with g_socket_create_source() will trigger after - * @timeout seconds of inactivity, with the requested condition - * set, at which point calling g_socket_receive(), g_socket_send(), - * g_socket_check_connect_result(), etc, will fail with - * %G_IO_ERROR_TIMED_OUT. - * - * If @timeout is 0 (the default), operations will never time out - * on their own. - * - * Note that if an I/O operation is interrupted by a signal, this may - * cause the timeout to be reset. - * - * Since: 2.26 - */ - - -/** - * g_socket_set_ttl: - * @socket: a #GSocket. - * @ttl: the time-to-live value for all unicast packets on @socket - * - * Sets the time-to-live for outgoing unicast packets on @socket. - * By default the platform-specific default value is used. - * - * Since: 2.32 - */ - - -/** - * g_socket_shutdown: - * @socket: a #GSocket - * @shutdown_read: whether to shut down the read side - * @shutdown_write: whether to shut down the write side - * @error: #GError for error reporting, or %NULL to ignore. - * - * Shut down part or all of a full-duplex connection. - * - * If @shutdown_read is %TRUE then the receiving side of the connection - * is shut down, and further reading is disallowed. - * - * If @shutdown_write is %TRUE then the sending side of the connection - * is shut down, and further writing is disallowed. - * - * It is allowed for both @shutdown_read and @shutdown_write to be %TRUE. - * - * One example where it is useful to shut down only one side of a connection is - * graceful disconnect for TCP connections where you close the sending side, - * then wait for the other side to close the connection, thus ensuring that the - * other side saw all sent data. - * - * Returns: %TRUE on success, %FALSE on error - * Since: 2.22 - */ - - -/** - * g_socket_speaks_ipv4: - * @socket: a #GSocket - * - * Checks if a socket is capable of speaking IPv4. - * - * IPv4 sockets are capable of speaking IPv4. On some operating systems - * and under some combinations of circumstances IPv6 sockets are also - * capable of speaking IPv4. See RFC 3493 section 3.7 for more - * information. - * - * No other types of sockets are currently considered as being capable - * of speaking IPv4. - * - * Returns: %TRUE if this socket can be used with IPv4. - * Since: 2.22 - */ - - -/** - * g_srv_target_copy: - * @target: a #GSrvTarget - * - * Copies @target - * - * Returns: a copy of @target - * Since: 2.22 - */ - - -/** - * g_srv_target_free: - * @target: a #GSrvTarget - * - * Frees @target - * - * Since: 2.22 - */ - - -/** - * g_srv_target_get_hostname: - * @target: a #GSrvTarget - * - * Gets @target's hostname (in ASCII form; if you are going to present - * this to the user, you should use g_hostname_is_ascii_encoded() to - * check if it contains encoded Unicode segments, and use - * g_hostname_to_unicode() to convert it if it does.) - * - * Returns: @target's hostname - * Since: 2.22 - */ - - -/** - * g_srv_target_get_port: - * @target: a #GSrvTarget - * - * Gets @target's port - * - * Returns: @target's port - * Since: 2.22 - */ - - -/** - * g_srv_target_get_priority: - * @target: a #GSrvTarget - * - * Gets @target's priority. You should not need to look at this; - * #GResolver already sorts the targets according to the algorithm in - * RFC 2782. - * - * Returns: @target's priority - * Since: 2.22 - */ - - -/** - * g_srv_target_get_weight: - * @target: a #GSrvTarget - * - * Gets @target's weight. You should not need to look at this; - * #GResolver already sorts the targets according to the algorithm in - * RFC 2782. - * - * Returns: @target's weight - * Since: 2.22 - */ - - -/** - * g_srv_target_list_sort: (skip) - * @targets: a #GList of #GSrvTarget - * - * Sorts @targets in place according to the algorithm in RFC 2782. - * - * Returns: (transfer full): the head of the sorted list. - * Since: 2.22 - */ - - -/** - * g_srv_target_new: - * @hostname: the host that the service is running on - * @port: the port that the service is running on - * @priority: the target's priority - * @weight: the target's weight - * - * Creates a new #GSrvTarget with the given parameters. - * - * You should not need to use this; normally #GSrvTargets are - * created by #GResolver. - * - * Returns: a new #GSrvTarget. - * Since: 2.22 - */ - - -/** - * g_static_resource_fini: - * @static_resource: pointer to a static #GStaticResource - * - * Finalized a GResource initialized by g_static_resource_init(). - * - * This is normally used by code generated by - * [glib-compile-resources][glib-compile-resources] - * and is not typically used by other code. - * - * Since: 2.32 - */ - - -/** - * g_static_resource_get_resource: - * @static_resource: pointer to a static #GStaticResource - * - * Gets the GResource that was registered by a call to g_static_resource_init(). - * - * This is normally used by code generated by - * [glib-compile-resources][glib-compile-resources] - * and is not typically used by other code. - * - * Returns: (transfer none): a #GResource - * Since: 2.32 - */ - - -/** - * g_static_resource_init: - * @static_resource: pointer to a static #GStaticResource - * - * Initializes a GResource from static data using a - * GStaticResource. - * - * This is normally used by code generated by - * [glib-compile-resources][glib-compile-resources] - * and is not typically used by other code. - * - * Since: 2.32 - */ - - -/** - * g_subprocess_communicate: - * @subprocess: a #GSubprocess - * @stdin_buf: (nullable): data to send to the stdin of the subprocess, or %NULL - * @cancellable: a #GCancellable - * @stdout_buf: (out) (nullable) (optional) (transfer full): data read from the subprocess stdout - * @stderr_buf: (out) (nullable) (optional) (transfer full): data read from the subprocess stderr - * @error: a pointer to a %NULL #GError pointer, or %NULL - * - * Communicate with the subprocess until it terminates, and all input - * and output has been completed. - * - * If @stdin_buf is given, the subprocess must have been created with - * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the - * stdin of the subprocess and the pipe is closed (ie: EOF). - * - * At the same time (as not to cause blocking when dealing with large - * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or - * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those - * streams. The data that was read is returned in @stdout and/or - * the @stderr. - * - * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, - * @stdout_buf will contain the data read from stdout. Otherwise, for - * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, - * @stdout_buf will be set to %NULL. Similar provisions apply to - * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE. - * - * As usual, any output variable may be given as %NULL to ignore it. - * - * If you desire the stdout and stderr data to be interleaved, create - * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and - * %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned - * in @stdout_buf and @stderr_buf will be set to %NULL. - * - * In case of any error (including cancellation), %FALSE will be - * returned with @error set. Some or all of the stdin data may have - * been written. Any stdout or stderr data that has been read will be - * discarded. None of the out variables (aside from @error) will have - * been set to anything in particular and should not be inspected. - * - * In the case that %TRUE is returned, the subprocess has exited and the - * exit status inspection APIs (eg: g_subprocess_get_if_exited(), - * g_subprocess_get_exit_status()) may be used. - * - * You should not attempt to use any of the subprocess pipes after - * starting this function, since they may be left in strange states, - * even if the operation was cancelled. You should especially not - * attempt to interact with the pipes while the operation is in progress - * (either from another thread or if using the asynchronous version). - * - * Returns: %TRUE if successful - * Since: 2.40 - */ - - -/** - * g_subprocess_communicate_async: - * @subprocess: Self - * @stdin_buf: (nullable): Input data, or %NULL - * @cancellable: (nullable): Cancellable - * @callback: Callback - * @user_data: User data - * - * Asynchronous version of g_subprocess_communicate(). Complete - * invocation with g_subprocess_communicate_finish(). - */ - - -/** - * g_subprocess_communicate_finish: - * @subprocess: Self - * @result: Result - * @stdout_buf: (out) (nullable) (optional) (transfer full): Return location for stdout data - * @stderr_buf: (out) (nullable) (optional) (transfer full): Return location for stderr data - * @error: Error - * - * Complete an invocation of g_subprocess_communicate_async(). - */ - - -/** - * g_subprocess_communicate_utf8: - * @subprocess: a #GSubprocess - * @stdin_buf: (nullable): data to send to the stdin of the subprocess, or %NULL - * @cancellable: a #GCancellable - * @stdout_buf: (out) (nullable) (optional) (transfer full): data read from the subprocess stdout - * @stderr_buf: (out) (nullable) (optional) (transfer full): data read from the subprocess stderr - * @error: a pointer to a %NULL #GError pointer, or %NULL - * - * Like g_subprocess_communicate(), but validates the output of the - * process as UTF-8, and returns it as a regular NUL terminated string. - * - * On error, @stdout_buf and @stderr_buf will be set to undefined values and - * should not be used. - */ - - -/** - * g_subprocess_communicate_utf8_async: - * @subprocess: Self - * @stdin_buf: (nullable): Input data, or %NULL - * @cancellable: Cancellable - * @callback: Callback - * @user_data: User data - * - * Asynchronous version of g_subprocess_communicate_utf8(). Complete - * invocation with g_subprocess_communicate_utf8_finish(). - */ - - -/** - * g_subprocess_communicate_utf8_finish: - * @subprocess: Self - * @result: Result - * @stdout_buf: (out) (nullable) (optional) (transfer full): Return location for stdout data - * @stderr_buf: (out) (nullable) (optional) (transfer full): Return location for stderr data - * @error: Error - * - * Complete an invocation of g_subprocess_communicate_utf8_async(). - */ - - -/** - * g_subprocess_force_exit: - * @subprocess: a #GSubprocess - * - * Use an operating-system specific method to attempt an immediate, - * forceful termination of the process. There is no mechanism to - * determine whether or not the request itself was successful; - * however, you can use g_subprocess_wait() to monitor the status of - * the process after calling this function. - * - * On Unix, this function sends %SIGKILL. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_get_exit_status: - * @subprocess: a #GSubprocess - * - * Check the exit status of the subprocess, given that it exited - * normally. This is the value passed to the exit() system call or the - * return value from main. - * - * This is equivalent to the system WEXITSTATUS macro. - * - * It is an error to call this function before g_subprocess_wait() and - * unless g_subprocess_get_if_exited() returned %TRUE. - * - * Returns: the exit status - * Since: 2.40 - */ - - -/** - * g_subprocess_get_identifier: - * @subprocess: a #GSubprocess - * - * On UNIX, returns the process ID as a decimal string. - * On Windows, returns the result of GetProcessId() also as a string. - * If the subprocess has terminated, this will return %NULL. - * - * Returns: (nullable): the subprocess identifier, or %NULL if the subprocess - * has terminated - * Since: 2.40 - */ - - -/** - * g_subprocess_get_if_exited: - * @subprocess: a #GSubprocess - * - * Check if the given subprocess exited normally (ie: by way of exit() - * or return from main()). - * - * This is equivalent to the system WIFEXITED macro. - * - * It is an error to call this function before g_subprocess_wait() has - * returned. - * - * Returns: %TRUE if the case of a normal exit - * Since: 2.40 - */ - - -/** - * g_subprocess_get_if_signaled: - * @subprocess: a #GSubprocess - * - * Check if the given subprocess terminated in response to a signal. - * - * This is equivalent to the system WIFSIGNALED macro. - * - * It is an error to call this function before g_subprocess_wait() has - * returned. - * - * Returns: %TRUE if the case of termination due to a signal - * Since: 2.40 - */ - - -/** - * g_subprocess_get_status: - * @subprocess: a #GSubprocess - * - * Gets the raw status code of the process, as from waitpid(). - * - * This value has no particular meaning, but it can be used with the - * macros defined by the system headers such as WIFEXITED. It can also - * be used with g_spawn_check_wait_status(). - * - * It is more likely that you want to use g_subprocess_get_if_exited() - * followed by g_subprocess_get_exit_status(). - * - * It is an error to call this function before g_subprocess_wait() has - * returned. - * - * Returns: the (meaningless) waitpid() exit status from the kernel - * Since: 2.40 - */ - - -/** - * g_subprocess_get_stderr_pipe: - * @subprocess: a #GSubprocess - * - * Gets the #GInputStream from which to read the stderr output of - * @subprocess. - * - * The process must have been created with %G_SUBPROCESS_FLAGS_STDERR_PIPE, - * otherwise %NULL will be returned. - * - * Returns: (nullable) (transfer none): the stderr pipe - * Since: 2.40 - */ - - -/** - * g_subprocess_get_stdin_pipe: - * @subprocess: a #GSubprocess - * - * Gets the #GOutputStream that you can write to in order to give data - * to the stdin of @subprocess. - * - * The process must have been created with %G_SUBPROCESS_FLAGS_STDIN_PIPE and - * not %G_SUBPROCESS_FLAGS_STDIN_INHERIT, otherwise %NULL will be returned. - * - * Returns: (nullable) (transfer none): the stdout pipe - * Since: 2.40 - */ - - -/** - * g_subprocess_get_stdout_pipe: - * @subprocess: a #GSubprocess - * - * Gets the #GInputStream from which to read the stdout output of - * @subprocess. - * - * The process must have been created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, - * otherwise %NULL will be returned. - * - * Returns: (nullable) (transfer none): the stdout pipe - * Since: 2.40 - */ - - -/** - * g_subprocess_get_successful: - * @subprocess: a #GSubprocess - * - * Checks if the process was "successful". A process is considered - * successful if it exited cleanly with an exit status of 0, either by - * way of the exit() system call or return from main(). - * - * It is an error to call this function before g_subprocess_wait() has - * returned. - * - * Returns: %TRUE if the process exited cleanly with a exit status of 0 - * Since: 2.40 - */ - - -/** - * g_subprocess_get_term_sig: - * @subprocess: a #GSubprocess - * - * Get the signal number that caused the subprocess to terminate, given - * that it terminated due to a signal. - * - * This is equivalent to the system WTERMSIG macro. - * - * It is an error to call this function before g_subprocess_wait() and - * unless g_subprocess_get_if_signaled() returned %TRUE. - * - * Returns: the signal causing termination - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_close: - * @self: a #GSubprocessLauncher - * - * Closes all the file descriptors previously passed to the object with - * g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc. - * - * After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or g_subprocess_launcher_spawnv() will - * return %G_IO_ERROR_CLOSED. This method is idempotent if - * called more than once. - * - * This function is called automatically when the #GSubprocessLauncher - * is disposed, but is provided separately so that garbage collected - * language bindings can call it earlier to guarantee when FDs are closed. - * - * Since: 2.68 - */ - - -/** - * g_subprocess_launcher_getenv: - * @self: a #GSubprocessLauncher - * @variable: (type filename): the environment variable to get - * - * Returns the value of the environment variable @variable in the - * environment of processes launched from this launcher. - * - * On UNIX, the returned string can be an arbitrary byte string. - * On Windows, it will be UTF-8. - * - * Returns: (nullable) (type filename): the value of the environment variable, - * %NULL if unset - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_new: - * @flags: #GSubprocessFlags - * - * Creates a new #GSubprocessLauncher. - * - * The launcher is created with the default options. A copy of the - * environment of the calling process is made at the time of this call - * and will be used as the environment that the process is launched in. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_set_child_setup: (skip) - * @self: a #GSubprocessLauncher - * @child_setup: a #GSpawnChildSetupFunc to use as the child setup function - * @user_data: user data for @child_setup - * @destroy_notify: a #GDestroyNotify for @user_data - * - * Sets up a child setup function. - * - * The child setup function will be called after fork() but before - * exec() on the child's side. - * - * @destroy_notify will not be automatically called on the child's side - * of the fork(). It will only be called when the last reference on the - * #GSubprocessLauncher is dropped or when a new child setup function is - * given. - * - * %NULL can be given as @child_setup to disable the functionality. - * - * Child setup functions are only available on UNIX. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_set_cwd: - * @self: a #GSubprocessLauncher - * @cwd: (type filename): the cwd for launched processes - * - * Sets the current working directory that processes will be launched - * with. - * - * By default processes are launched with the current working directory - * of the launching process at the time of launch. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_set_environ: - * @self: a #GSubprocessLauncher - * @env: (array zero-terminated=1) (element-type filename) (transfer none): - * the replacement environment - * - * Replace the entire environment of processes launched from this - * launcher with the given 'environ' variable. - * - * Typically you will build this variable by using g_listenv() to copy - * the process 'environ' and using the functions g_environ_setenv(), - * g_environ_unsetenv(), etc. - * - * As an alternative, you can use g_subprocess_launcher_setenv(), - * g_subprocess_launcher_unsetenv(), etc. - * - * Pass an empty array to set an empty environment. Pass %NULL to inherit the - * parent process’ environment. As of GLib 2.54, the parent process’ environment - * will be copied when g_subprocess_launcher_set_environ() is called. - * Previously, it was copied when the subprocess was executed. This means the - * copied environment may now be modified (using g_subprocess_launcher_setenv(), - * etc.) before launching the subprocess. - * - * On UNIX, all strings in this array can be arbitrary byte strings. - * On Windows, they should be in UTF-8. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_set_flags: - * @self: a #GSubprocessLauncher - * @flags: #GSubprocessFlags - * - * Sets the flags on the launcher. - * - * The default flags are %G_SUBPROCESS_FLAGS_NONE. - * - * You may not set flags that specify conflicting options for how to - * handle a particular stdio stream (eg: specifying both - * %G_SUBPROCESS_FLAGS_STDIN_PIPE and - * %G_SUBPROCESS_FLAGS_STDIN_INHERIT). - * - * You may also not set a flag that conflicts with a previous call to a - * function like g_subprocess_launcher_set_stdin_file_path() or - * g_subprocess_launcher_take_stdout_fd(). - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_set_stderr_file_path: - * @self: a #GSubprocessLauncher - * @path: (type filename) (nullable): a filename or %NULL - * - * Sets the file path to use as the stderr for spawned processes. - * - * If @path is %NULL then any previously given path is unset. - * - * The file will be created or truncated when the process is spawned, as - * would be the case if using '2>' at the shell. - * - * If you want to send both stdout and stderr to the same file then use - * %G_SUBPROCESS_FLAGS_STDERR_MERGE. - * - * You may not set a stderr file path if a stderr fd is already set or - * if the launcher flags contain any flags directing stderr elsewhere. - * - * This feature is only available on UNIX. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_set_stdin_file_path: - * @self: a #GSubprocessLauncher - * @path: - * - * Sets the file path to use as the stdin for spawned processes. - * - * If @path is %NULL then any previously given path is unset. - * - * The file must exist or spawning the process will fail. - * - * You may not set a stdin file path if a stdin fd is already set or if - * the launcher flags contain any flags directing stdin elsewhere. - * - * This feature is only available on UNIX. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_set_stdout_file_path: - * @self: a #GSubprocessLauncher - * @path: (type filename) (nullable): a filename or %NULL - * - * Sets the file path to use as the stdout for spawned processes. - * - * If @path is %NULL then any previously given path is unset. - * - * The file will be created or truncated when the process is spawned, as - * would be the case if using '>' at the shell. - * - * You may not set a stdout file path if a stdout fd is already set or - * if the launcher flags contain any flags directing stdout elsewhere. - * - * This feature is only available on UNIX. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_setenv: - * @self: a #GSubprocessLauncher - * @variable: (type filename): the environment variable to set, - * must not contain '=' - * @value: (type filename): the new value for the variable - * @overwrite: whether to change the variable if it already exists - * - * Sets the environment variable @variable in the environment of - * processes launched from this launcher. - * - * On UNIX, both the variable's name and value can be arbitrary byte - * strings, except that the variable's name cannot contain '='. - * On Windows, they should be in UTF-8. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_spawn: - * @self: a #GSubprocessLauncher - * @error: Error - * @argv0: Command line arguments - * @...: Continued arguments, %NULL terminated - * - * Creates a #GSubprocess given a provided varargs list of arguments. - * - * Since: 2.40 - * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set) - */ - - -/** - * g_subprocess_launcher_spawnv: - * @self: a #GSubprocessLauncher - * @argv: (array zero-terminated=1) (element-type filename): Command line arguments - * @error: Error - * - * Creates a #GSubprocess given a provided array of arguments. - * - * Since: 2.40 - * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set) - */ - - -/** - * g_subprocess_launcher_take_fd: - * @self: a #GSubprocessLauncher - * @source_fd: File descriptor in parent process - * @target_fd: Target descriptor for child process - * - * Transfer an arbitrary file descriptor from parent process to the - * child. This function takes ownership of the @source_fd; it will be closed - * in the parent when @self is freed. - * - * By default, all file descriptors from the parent will be closed. - * This function allows you to create (for example) a custom `pipe()` or - * `socketpair()` before launching the process, and choose the target - * descriptor in the child. - * - * An example use case is GNUPG, which has a command line argument - * `--passphrase-fd` providing a file descriptor number where it expects - * the passphrase to be written. - */ - - -/** - * g_subprocess_launcher_take_stderr_fd: - * @self: a #GSubprocessLauncher - * @fd: a file descriptor, or -1 - * - * Sets the file descriptor to use as the stderr for spawned processes. - * - * If @fd is -1 then any previously given fd is unset. - * - * Note that the default behaviour is to pass stderr through to the - * stderr of the parent process. - * - * The passed @fd belongs to the #GSubprocessLauncher. It will be - * automatically closed when the launcher is finalized. The file - * descriptor will also be closed on the child side when executing the - * spawned process. - * - * You may not set a stderr fd if a stderr file path is already set or - * if the launcher flags contain any flags directing stderr elsewhere. - * - * This feature is only available on UNIX. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_take_stdin_fd: - * @self: a #GSubprocessLauncher - * @fd: a file descriptor, or -1 - * - * Sets the file descriptor to use as the stdin for spawned processes. - * - * If @fd is -1 then any previously given fd is unset. - * - * Note that if your intention is to have the stdin of the calling - * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT - * is a better way to go about doing that. - * - * The passed @fd is noted but will not be touched in the current - * process. It is therefore necessary that it be kept open by the - * caller until the subprocess is spawned. The file descriptor will - * also not be explicitly closed on the child side, so it must be marked - * O_CLOEXEC if that's what you want. - * - * You may not set a stdin fd if a stdin file path is already set or if - * the launcher flags contain any flags directing stdin elsewhere. - * - * This feature is only available on UNIX. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_take_stdout_fd: - * @self: a #GSubprocessLauncher - * @fd: a file descriptor, or -1 - * - * Sets the file descriptor to use as the stdout for spawned processes. - * - * If @fd is -1 then any previously given fd is unset. - * - * Note that the default behaviour is to pass stdout through to the - * stdout of the parent process. - * - * The passed @fd is noted but will not be touched in the current - * process. It is therefore necessary that it be kept open by the - * caller until the subprocess is spawned. The file descriptor will - * also not be explicitly closed on the child side, so it must be marked - * O_CLOEXEC if that's what you want. - * - * You may not set a stdout fd if a stdout file path is already set or - * if the launcher flags contain any flags directing stdout elsewhere. - * - * This feature is only available on UNIX. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_launcher_unsetenv: - * @self: a #GSubprocessLauncher - * @variable: (type filename): the environment variable to unset, - * must not contain '=' - * - * Removes the environment variable @variable from the environment of - * processes launched from this launcher. - * - * On UNIX, the variable's name can be an arbitrary byte string not - * containing '='. On Windows, it should be in UTF-8. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_new: (skip) - * @flags: flags that define the behaviour of the subprocess - * @error: (nullable): return location for an error, or %NULL - * @argv0: first commandline argument to pass to the subprocess - * @...: more commandline arguments, followed by %NULL - * - * Create a new process with the given flags and varargs argument - * list. By default, matching the g_spawn_async() defaults, the - * child's stdin will be set to the system null device, and - * stdout/stderr will be inherited from the parent. You can use - * @flags to control this behavior. - * - * The argument list must be terminated with %NULL. - * - * Returns: A newly created #GSubprocess, or %NULL on error (and @error - * will be set) - * Since: 2.40 - */ - - -/** - * g_subprocess_newv: (rename-to g_subprocess_new) - * @argv: (array zero-terminated=1) (element-type filename): commandline arguments for the subprocess - * @flags: flags that define the behaviour of the subprocess - * @error: (nullable): return location for an error, or %NULL - * - * Create a new process with the given flags and argument list. - * - * The argument list is expected to be %NULL-terminated. - * - * Returns: A newly created #GSubprocess, or %NULL on error (and @error - * will be set) - * Since: 2.40 - */ - - -/** - * g_subprocess_send_signal: - * @subprocess: a #GSubprocess - * @signal_num: the signal number to send - * - * Sends the UNIX signal @signal_num to the subprocess, if it is still - * running. - * - * This API is race-free. If the subprocess has terminated, it will not - * be signalled. - * - * This API is not available on Windows. - * - * Since: 2.40 - */ - - -/** - * g_subprocess_wait: - * @subprocess: a #GSubprocess - * @cancellable: a #GCancellable - * @error: a #GError - * - * Synchronously wait for the subprocess to terminate. - * - * After the process terminates you can query its exit status with - * functions such as g_subprocess_get_if_exited() and - * g_subprocess_get_exit_status(). - * - * This function does not fail in the case of the subprocess having - * abnormal termination. See g_subprocess_wait_check() for that. - * - * Cancelling @cancellable doesn't kill the subprocess. Call - * g_subprocess_force_exit() if it is desirable. - * - * Returns: %TRUE on success, %FALSE if @cancellable was cancelled - * Since: 2.40 - */ - - -/** - * g_subprocess_wait_async: - * @subprocess: a #GSubprocess - * @cancellable: a #GCancellable, or %NULL - * @callback: a #GAsyncReadyCallback to call when the operation is complete - * @user_data: user_data for @callback - * - * Wait for the subprocess to terminate. - * - * This is the asynchronous version of g_subprocess_wait(). - * - * Since: 2.40 - */ - - -/** - * g_subprocess_wait_check: - * @subprocess: a #GSubprocess - * @cancellable: a #GCancellable - * @error: a #GError - * - * Combines g_subprocess_wait() with g_spawn_check_wait_status(). - * - * Returns: %TRUE on success, %FALSE if process exited abnormally, or - * @cancellable was cancelled - * Since: 2.40 - */ - - -/** - * g_subprocess_wait_check_async: - * @subprocess: a #GSubprocess - * @cancellable: a #GCancellable, or %NULL - * @callback: a #GAsyncReadyCallback to call when the operation is complete - * @user_data: user_data for @callback - * - * Combines g_subprocess_wait_async() with g_spawn_check_wait_status(). - * - * This is the asynchronous version of g_subprocess_wait_check(). - * - * Since: 2.40 - */ - - -/** - * g_subprocess_wait_check_finish: - * @subprocess: a #GSubprocess - * @result: the #GAsyncResult passed to your #GAsyncReadyCallback - * @error: a pointer to a %NULL #GError, or %NULL - * - * Collects the result of a previous call to - * g_subprocess_wait_check_async(). - * - * Returns: %TRUE if successful, or %FALSE with @error set - * Since: 2.40 - */ - - -/** - * g_subprocess_wait_finish: - * @subprocess: a #GSubprocess - * @result: the #GAsyncResult passed to your #GAsyncReadyCallback - * @error: a pointer to a %NULL #GError, or %NULL - * - * Collects the result of a previous call to - * g_subprocess_wait_async(). - * - * Returns: %TRUE if successful, or %FALSE with @error set - * Since: 2.40 - */ - - -/** - * 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 [priority][io-priority], and sets @source's - * callback to @callback, with @task as the callback's `user_data`. - * - * It will set the @source’s name to the task’s name (as set with - * g_task_set_name()), if one has been set. - * - * This takes a reference on @task until @source is destroyed. - * - * Since: 2.36 - */ - - -/** - * 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_completed: - * @task: a #GTask. - * - * Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after - * the task’s callback is invoked, and will return %FALSE if called from inside - * the callback. - * - * Returns: %TRUE if the task has completed, %FALSE otherwise. - * Since: 2.44 - */ - - -/** - * g_task_get_context: - * @task: a #GTask - * - * Gets the #GMainContext that @task will return its result in (that - * is, the context that was the - * [thread-default main context][g-main-context-push-thread-default] - * 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_name: - * @task: a #GTask - * - * Gets @task’s name. See g_task_set_name(). - * - * Returns: (nullable) (transfer none): @task’s name, or %NULL - * Since: 2.60 - */ - - -/** - * g_task_get_priority: - * @task: a #GTask - * - * 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) (nullable) (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 `task_data`. - * - * Returns: (transfer none): @task's `task_data`. - * 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: (nullable) (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: (nullable) (type GObject): the #GObject that owns - * this task, or %NULL. - * @cancellable: (nullable): 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 - * [thread-default main context][g-main-context-push-thread-default]. - * - * 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_propagate_value: - * @task: a #GTask - * @value: (out caller-allocates): return location for the #GValue - * @error: return location for a #GError - * - * Gets the result of @task as a #GValue, and transfers ownership of - * that value to the caller. As with g_task_return_value(), this is - * a generic low-level method; g_task_propagate_pointer() and the like - * will usually be more useful for C code. - * - * If the task resulted in an error, or was cancelled, then this will - * instead set @error and return %FALSE. - * - * Since this method transfers ownership of the return value (or - * error) to the caller, you may only call it once. - * - * Returns: %TRUE if @task succeeded, %FALSE on error. - * Since: 2.64 - */ - - -/** - * g_task_report_error: - * @source_object: (nullable) (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: (nullable) (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: (nullable) (transfer full): the pointer result of a task - * function - * @result_destroy: (nullable): 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_return_value: - * @task: a #GTask - * @result: (nullable) (transfer none): the #GValue result of - * a task function - * - * Sets @task's result to @result (by copying it) and completes the task. - * - * If @result is %NULL then a #GValue of type #G_TYPE_POINTER - * with a value of %NULL will be used for the result. - * - * This is a very generic low-level method intended primarily for use - * by language bindings; for C code, g_task_return_pointer() and the - * like will normally be much easier to use. - * - * Since: 2.64 - */ - - -/** - * g_task_run_in_thread: - * @task: a #GTask - * @task_func: (scope async): 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. - * - * Although GLib currently rate-limits the tasks queued via - * g_task_run_in_thread(), you should not assume that it will always - * do this. If you have a very large number of tasks to run (several tens of - * tasks), but don't want them to all run at once, you should only queue a - * limited number of them (around ten) at a time. - * - * Since: 2.36 - */ - - -/** - * g_task_run_in_thread_sync: - * @task: a #GTask - * @task_func: (scope async): 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 - * `callback`, but note that even if the task does - * have a callback, it will not be invoked when @task_func returns. - * #GTask:completed will be set to %TRUE just before this function returns. - * - * Although GLib currently rate-limits the tasks queued via - * g_task_run_in_thread_sync(), you should not assume that it will - * always do this. If you have a very large number of tasks to run, - * but don't want them to all run at once, you should only queue a - * limited number of them at a time. - * - * 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_name: - * @task: a #GTask - * @name: (nullable): a human readable name for the task, or %NULL to unset it - * - * Sets @task’s name, used in debugging and profiling. The name defaults to - * %NULL. - * - * The task name should describe in a human readable way what the task does. - * For example, ‘Open file’ or ‘Connect to network host’. It is used to set the - * name of the #GSource used for idle completion of the task. - * - * This function may only be called before the @task is first used in a thread - * other than the one it was constructed in. - * - * Since: 2.60 - */ - - -/** - * g_task_set_priority: - * @task: the #GTask - * @priority: the [priority][io-priority] 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 - * uninterruptible 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: (nullable): task-specific data - * @task_data_destroy: (nullable): #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 - * - * Checks if graceful disconnects are used. See - * g_tcp_connection_set_graceful_disconnect(). - * - * Returns: %TRUE if graceful disconnect is used on close, %FALSE otherwise - * Since: 2.22 - */ - - -/** - * g_tcp_connection_set_graceful_disconnect: - * @connection: a #GTcpConnection - * @graceful_disconnect: Whether to do graceful disconnects or not - * - * This enables graceful disconnects on close. A graceful disconnect - * means that we signal the receiving end that the connection is terminated - * and wait for it to close the connection before closing the connection. - * - * A graceful disconnect means that we can be sure that we successfully sent - * all the outstanding data to the other end, or get an error reported. - * However, it also means we have to wait for all the data to reach the - * other side and for it to acknowledge this by closing the socket, which may - * take a while. For this reason it is disabled by default. - * - * Since: 2.22 - */ - - -/** - * g_tcp_wrapper_connection_get_base_io_stream: - * @conn: a #GTcpWrapperConnection - * - * Gets @conn's base #GIOStream - * - * Returns: (transfer none): @conn's base #GIOStream - */ - - -/** - * g_tcp_wrapper_connection_new: - * @base_io_stream: the #GIOStream to wrap - * @socket: the #GSocket associated with @base_io_stream - * - * Wraps @base_io_stream and @socket together as a #GSocketConnection. - * - * Returns: the new #GSocketConnection. - * Since: 2.28 - */ - - -/** - * g_test_dbus_add_service_dir: - * @self: a #GTestDBus - * @path: path to a directory containing .service files - * - * Add a path where dbus-daemon will look up .service files. This can't be - * called after g_test_dbus_up(). - */ - - -/** - * g_test_dbus_down: - * @self: a #GTestDBus - * - * Stop the session bus started by g_test_dbus_up(). - * - * This will wait for the singleton returned by g_bus_get() or g_bus_get_sync() - * to be destroyed. This is done to ensure that the next unit test won't get a - * leaked singleton from this test. - */ - - -/** - * g_test_dbus_get_bus_address: - * @self: a #GTestDBus - * - * Get the address on which dbus-daemon is running. If g_test_dbus_up() has not - * been called yet, %NULL is returned. This can be used with - * g_dbus_connection_new_for_address(). - * - * Returns: (nullable): the address of the bus, or %NULL. - */ - - -/** - * g_test_dbus_get_flags: - * @self: a #GTestDBus - * - * Get the flags of the #GTestDBus object. - * - * Returns: the value of #GTestDBus:flags property - */ - - -/** - * g_test_dbus_new: - * @flags: a #GTestDBusFlags - * - * Create a new #GTestDBus object. - * - * Returns: (transfer full): a new #GTestDBus. - */ - - -/** - * g_test_dbus_stop: - * @self: a #GTestDBus - * - * Stop the session bus started by g_test_dbus_up(). - * - * Unlike g_test_dbus_down(), this won't verify the #GDBusConnection - * singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit - * tests wanting to verify behaviour after the session bus has been stopped - * can use this function but should still call g_test_dbus_down() when done. - */ - - -/** - * g_test_dbus_unset: - * - * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test - * won't use user's session bus. - * - * This is useful for unit tests that want to verify behaviour when no session - * bus is running. It is not necessary to call this if unit test already calls - * g_test_dbus_up() before acquiring the session bus. - */ - - -/** - * g_test_dbus_up: - * @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 bus. - * - * If this function is called from setup callback of g_test_add(), - * g_test_dbus_down() must be called in its teardown callback. - * - * If this function is called from unit test's main(), then g_test_dbus_down() - * must be called after g_test_run(). - */ - - -/** - * g_themed_icon_append_name: - * @icon: a #GThemedIcon - * @iconname: name of icon to append to list of icons from within @icon. - * - * Append a name to the list of icons from within @icon. - * - * Note that doing so invalidates the hash computed by prior calls - * to g_icon_hash(). - */ - - -/** - * g_themed_icon_get_names: - * @icon: a #GThemedIcon. - * - * Gets the names of icons from within @icon. - * - * Returns: (transfer none): a list of icon names. - */ - - -/** - * g_themed_icon_new: - * @iconname: a string containing an icon name. - * - * Creates a new themed icon for @iconname. - * - * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon. - */ - - -/** - * g_themed_icon_new_from_names: - * @iconnames: (array length=len): an array of strings containing icon names. - * @len: the length of the @iconnames array, or -1 if @iconnames is - * %NULL-terminated - * - * Creates a new themed icon for @iconnames. - * - * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon - */ - - -/** - * g_themed_icon_new_with_default_fallbacks: - * @iconname: a string containing an icon name - * - * Creates a new themed icon for @iconname, and all the names - * that can be created by shortening @iconname at '-' characters. - * - * In the following example, @icon1 and @icon2 are equivalent: - * |[ - * const char *names[] = { - * "gnome-dev-cdrom-audio", - * "gnome-dev-cdrom", - * "gnome-dev", - * "gnome" - * }; - * - * icon1 = g_themed_icon_new_from_names (names, 4); - * icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio"); - * ]| - * - * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon. - */ - - -/** - * g_themed_icon_prepend_name: - * @icon: a #GThemedIcon - * @iconname: name of icon to prepend to list of icons from within @icon. - * - * Prepend a name to the list of icons from within @icon. - * - * Note that doing so invalidates the hash computed by prior calls - * to g_icon_hash(). - * - * Since: 2.18 - */ - - -/** - * g_themed_icon_update_names: - * @themed: a #GThemedIcon. - * - * Update the actual icon name list, based on the requested names (from - * construction, or later added with g_themed_icon_prepend_name() and - * g_themed_icon_append_name()). - * The order of the list matters, indicating priority: - * - The first requested icon is first in priority. - * - If "use-default-fallbacks" is #TRUE, then it is followed by all its - * fallbacks (starting from top to lower context levels). - * - Then next requested icons, and optionally their fallbacks, follow. - * - Finally all the style variants (symbolic or regular, opposite to whatever - * is the requested style) follow in the same order. - * - * An icon is not added twice in the list if it was previously added. - * - * For instance, if requested names are: - * [ "some-icon-symbolic", "some-other-icon" ] - * and use-default-fallbacks is TRUE, the final name list shall be: - * [ "some-icon-symbolic", "some-symbolic", "some-other-icon", - * "some-other", "some", "some-icon", "some-other-icon-symbolic", - * "some-other-symbolic" ] - * - * Returns: (transfer full) (type GThemedIcon): a new #GThemedIcon - */ - - -/** - * g_threaded_socket_service_new: - * @max_threads: the maximal number of threads to execute concurrently - * handling incoming clients, -1 means no limit - * - * Creates a new #GThreadedSocketService with no listeners. Listeners - * must be added with one of the #GSocketListener "add" methods. - * - * Returns: a new #GSocketService. - * Since: 2.22 - */ - - -/** - * g_tls_backend_get_certificate_type: - * @backend: the #GTlsBackend - * - * Gets the #GType of @backend's #GTlsCertificate implementation. - * - * Returns: the #GType of @backend's #GTlsCertificate - * implementation. - * Since: 2.28 - */ - - -/** - * g_tls_backend_get_client_connection_type: - * @backend: the #GTlsBackend - * - * Gets the #GType of @backend's #GTlsClientConnection implementation. - * - * Returns: the #GType of @backend's #GTlsClientConnection - * implementation. - * Since: 2.28 - */ - - -/** - * g_tls_backend_get_default: - * - * Gets the default #GTlsBackend for the system. - * - * Returns: (not nullable) (transfer none): a #GTlsBackend, which will be a - * dummy object if no TLS backend is available - * Since: 2.28 - */ - - -/** - * g_tls_backend_get_default_database: - * @backend: the #GTlsBackend - * - * Gets the default #GTlsDatabase used to verify TLS connections. - * - * Returns: (transfer full): the default database, which should be - * unreffed when done. - * Since: 2.30 - */ - - -/** - * g_tls_backend_get_dtls_client_connection_type: - * @backend: the #GTlsBackend - * - * Gets the #GType of @backend’s #GDtlsClientConnection implementation. - * - * Returns: the #GType of @backend’s #GDtlsClientConnection - * implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. - * Since: 2.48 - */ - - -/** - * g_tls_backend_get_dtls_server_connection_type: - * @backend: the #GTlsBackend - * - * Gets the #GType of @backend’s #GDtlsServerConnection implementation. - * - * Returns: the #GType of @backend’s #GDtlsServerConnection - * implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS. - * Since: 2.48 - */ - - -/** - * g_tls_backend_get_file_database_type: - * @backend: the #GTlsBackend - * - * Gets the #GType of @backend's #GTlsFileDatabase implementation. - * - * Returns: the #GType of backend's #GTlsFileDatabase implementation. - * Since: 2.30 - */ - - -/** - * g_tls_backend_get_server_connection_type: - * @backend: the #GTlsBackend - * - * Gets the #GType of @backend's #GTlsServerConnection implementation. - * - * Returns: the #GType of @backend's #GTlsServerConnection - * implementation. - * Since: 2.28 - */ - - -/** - * g_tls_backend_set_default_database: - * @backend: the #GTlsBackend - * @database: (nullable): the #GTlsDatabase - * - * Set the default #GTlsDatabase used to verify TLS connections - * - * Any subsequent call to g_tls_backend_get_default_database() will return - * the database set in this call. Existing databases and connections are not - * modified. - * - * Setting a %NULL default database will reset to using the system default - * database as if g_tls_backend_set_default_database() had never been called. - * - * Since: 2.60 - */ - - -/** - * g_tls_backend_supports_dtls: - * @backend: the #GTlsBackend - * - * Checks if DTLS is supported. DTLS support may not be available even if TLS - * support is available, and vice-versa. - * - * Returns: whether DTLS is supported - * Since: 2.48 - */ - - -/** - * g_tls_backend_supports_tls: - * @backend: the #GTlsBackend - * - * Checks if TLS is supported; if this returns %FALSE for the default - * #GTlsBackend, it means no "real" TLS backend is available. - * - * Returns: whether or not TLS is supported - * Since: 2.28 - */ - - -/** - * g_tls_certificate_get_dns_names: - * @cert: a #GTlsCertificate - * - * Gets the value of #GTlsCertificate:dns-names. - * - * Returns: (nullable) (element-type GBytes) (transfer container): A #GPtrArray of - * #GBytes elements, or %NULL if it's not available. - * Since: 2.70 - */ - - -/** - * g_tls_certificate_get_ip_addresses: - * @cert: a #GTlsCertificate - * - * Gets the value of #GTlsCertificate:ip-addresses. - * - * Returns: (nullable) (element-type GInetAddress) (transfer container): A #GPtrArray - * of #GInetAddress elements, or %NULL if it's not available. - * Since: 2.70 - */ - - -/** - * g_tls_certificate_get_issuer: - * @cert: a #GTlsCertificate - * - * Gets the #GTlsCertificate representing @cert's issuer, if known - * - * Returns: (nullable) (transfer none): The certificate of @cert's issuer, - * or %NULL if @cert is self-signed or signed with an unknown - * certificate. - * Since: 2.28 - */ - - -/** - * g_tls_certificate_get_issuer_name: - * @cert: a #GTlsCertificate - * - * Returns the issuer name from the certificate. - * - * Returns: (nullable) (transfer full): The issuer name, or %NULL if it's not available. - * Since: 2.70 - */ - - -/** - * g_tls_certificate_get_not_valid_after: - * @cert: a #GTlsCertificate - * - * Returns the time at which the certificate became or will become invalid. - * - * Returns: (nullable) (transfer full): The not-valid-after date, or %NULL if it's not available. - * Since: 2.70 - */ - - -/** - * g_tls_certificate_get_not_valid_before: - * @cert: a #GTlsCertificate - * - * Returns the time at which the certificate became or will become valid. - * - * Returns: (nullable) (transfer full): The not-valid-before date, or %NULL if it's not available. - * Since: 2.70 - */ - - -/** - * g_tls_certificate_get_subject_name: - * @cert: a #GTlsCertificate - * - * Returns the subject name from the certificate. - * - * Returns: (nullable) (transfer full): The subject name, or %NULL if it's not available. - * Since: 2.70 - */ - - -/** - * g_tls_certificate_is_same: - * @cert_one: first certificate to compare - * @cert_two: second certificate to compare - * - * Check if two #GTlsCertificate objects represent the same certificate. - * The raw DER byte data of the two certificates are checked for equality. - * This has the effect that two certificates may compare equal even if - * their #GTlsCertificate:issuer, #GTlsCertificate:private-key, or - * #GTlsCertificate:private-key-pem properties differ. - * - * Returns: whether the same or not - * Since: 2.34 - */ - - -/** - * g_tls_certificate_list_new_from_file: - * @file: (type filename): file containing PEM-encoded certificates to import - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates one or more #GTlsCertificates from the PEM-encoded - * data in @file. If @file cannot be read or parsed, the function will - * return %NULL and set @error. If @file does not contain any - * PEM-encoded certificates, this will return an empty list and not - * set @error. - * - * Returns: (element-type Gio.TlsCertificate) (transfer full): a - * #GList containing #GTlsCertificate objects. You must free the list - * and its contents when you are done with it. - * Since: 2.28 - */ - - -/** - * g_tls_certificate_new_from_file: - * @file: (type filename): file containing a PEM-encoded certificate to import - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a #GTlsCertificate from the PEM-encoded data in @file. The - * returned certificate will be the first certificate found in @file. As - * of GLib 2.44, if @file contains more certificates it will try to load - * a certificate chain. All certificates will be verified in the order - * found (top-level certificate should be the last one in the file) and - * the #GTlsCertificate:issuer property of each certificate will be set - * accordingly if the verification succeeds. If any certificate in the - * chain cannot be verified, the first certificate in the file will - * still be returned. - * - * If @file cannot be read or parsed, the function will return %NULL and - * set @error. Otherwise, this behaves like - * g_tls_certificate_new_from_pem(). - * - * Returns: the new certificate, or %NULL on error - * Since: 2.28 - */ - - -/** - * g_tls_certificate_new_from_files: - * @cert_file: (type filename): file containing one or more PEM-encoded - * certificates to import - * @key_file: (type filename): file containing a PEM-encoded private key - * to import - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a #GTlsCertificate from the PEM-encoded data in @cert_file - * and @key_file. The returned certificate will be the first certificate - * found in @cert_file. As of GLib 2.44, if @cert_file contains more - * certificates it will try to load a certificate chain. All - * certificates will be verified in the order found (top-level - * certificate should be the last one in the file) and the - * #GTlsCertificate:issuer property of each certificate will be set - * accordingly if the verification succeeds. If any certificate in the - * chain cannot be verified, the first certificate in the file will - * still be returned. - * - * If either file cannot be read or parsed, the function will return - * %NULL and set @error. Otherwise, this behaves like - * g_tls_certificate_new_from_pem(). - * - * Returns: the new certificate, or %NULL on error - * Since: 2.28 - */ - - -/** - * g_tls_certificate_new_from_pem: - * @data: PEM-encoded certificate data - * @length: the length of @data, or -1 if it's 0-terminated. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a #GTlsCertificate from the PEM-encoded data in @data. If - * @data includes both a certificate and a private key, then the - * returned certificate will include the private key data as well. (See - * the #GTlsCertificate:private-key-pem property for information about - * supported formats.) - * - * The returned certificate will be the first certificate found in - * @data. As of GLib 2.44, if @data contains more certificates it will - * try to load a certificate chain. All certificates will be verified in - * the order found (top-level certificate should be the last one in the - * file) and the #GTlsCertificate:issuer property of each certificate - * will be set accordingly if the verification succeeds. If any - * certificate in the chain cannot be verified, the first certificate in - * the file will still be returned. - * - * Returns: the new certificate, or %NULL if @data is invalid - * Since: 2.28 - */ - - -/** - * g_tls_certificate_new_from_pkcs11_uris: - * @pkcs11_uri: A PKCS \#11 URI - * @private_key_pkcs11_uri: (nullable): A PKCS \#11 URI - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a #GTlsCertificate from a - * [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) URI. - * - * An example @pkcs11_uri would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01` - * - * Where the token’s layout is: - * - * |[ - * Object 0: - * URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private - * Type: Private key (RSA-2048) - * ID: 01 - * - * Object 1: - * URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert - * Type: X.509 Certificate (RSA-2048) - * ID: 01 - * ]| - * - * In this case the certificate and private key would both be detected and used as expected. - * @pkcs_uri may also just reference an X.509 certificate object and then optionally - * @private_key_pkcs11_uri allows using a private key exposed under a different URI. - * - * Note that the private key is not accessed until usage and may fail or require a PIN later. - * - * Returns: (transfer full): the new certificate, or %NULL on error - * Since: 2.68 - */ - - -/** - * g_tls_certificate_verify: - * @cert: a #GTlsCertificate - * @identity: (nullable): the expected peer identity - * @trusted_ca: (nullable): the certificate of a trusted authority - * - * This verifies @cert and returns a set of #GTlsCertificateFlags - * indicating any problems found with it. This can be used to verify a - * certificate outside the context of making a connection, or to - * check a certificate against a CA that is not part of the system - * CA database. - * - * If @identity is not %NULL, @cert's name(s) will be compared against - * it, and %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return - * value if it does not match. If @identity is %NULL, that bit will - * never be set in the return value. - * - * If @trusted_ca is not %NULL, then @cert (or one of the certificates - * in its chain) must be signed by it, or else - * %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If - * @trusted_ca is %NULL, that bit will never be set in the return - * value. - * - * (All other #GTlsCertificateFlags values will always be set or unset - * as appropriate.) - * - * Because TLS session context is not used, #GTlsCertificate may not - * perform as many checks on the certificates as #GTlsConnection would. - * For example, certificate constraints cannot be honored, and some - * revocation checks cannot be performed. The best way to verify TLS - * certificates used by a TLS connection is to let #GTlsConnection - * handle the verification. - * - * Returns: the appropriate #GTlsCertificateFlags - * Since: 2.28 - */ - - -/** - * g_tls_channel_binding_error_quark: - * - * Gets the TLS channel binding error quark. - * - * Returns: a #GQuark. - * Since: 2.66 - */ - - -/** - * g_tls_client_connection_copy_session_state: - * @conn: a #GTlsClientConnection - * @source: a #GTlsClientConnection - * - * Possibly copies session state from one connection to another, for use - * in TLS session resumption. This is not normally needed, but may be - * used when the same session needs to be used between different - * endpoints, as is required by some protocols, such as FTP over TLS. - * @source should have already completed a handshake and, since TLS 1.3, - * it should have been used to read data at least once. @conn should not - * have completed a handshake. - * - * It is not possible to know whether a call to this function will - * actually do anything. Because session resumption is normally used - * only for performance benefit, the TLS backend might not implement - * this function. Even if implemented, it may not actually succeed in - * allowing @conn to resume @source's TLS session, because the server - * may not have sent a session resumption token to @source, or it may - * refuse to accept the token from @conn. There is no way to know - * whether a call to this function is actually successful. - * - * Using this function is not required to benefit from session - * resumption. If the TLS backend supports session resumption, the - * session will be resumed automatically if it is possible to do so - * without weakening the privacy guarantees normally provided by TLS, - * without need to call this function. For example, with TLS 1.3, - * a session ticket will be automatically copied from any - * #GTlsClientConnection that has previously received session tickets - * from the server, provided a ticket is available that has not - * previously been used for session resumption, since session ticket - * reuse would be a privacy weakness. Using this function causes the - * ticket to be copied without regard for privacy considerations. - * - * Since: 2.46 - */ - - -/** - * g_tls_client_connection_get_accepted_cas: - * @conn: the #GTlsClientConnection - * - * Gets the list of distinguished names of the Certificate Authorities - * that the server will accept certificates from. This will be set - * during the TLS handshake if the server requests a certificate. - * Otherwise, it will be %NULL. - * - * Each item in the list is a #GByteArray which contains the complete - * subject DN of the certificate authority. - * - * Returns: (element-type GByteArray) (transfer full): the list of - * CA DNs. You should unref each element with g_byte_array_unref() and then - * the free the list with g_list_free(). - * Since: 2.28 - */ - - -/** - * g_tls_client_connection_get_server_identity: - * @conn: the #GTlsClientConnection - * - * Gets @conn's expected server identity - * - * Returns: (nullable) (transfer none): a #GSocketConnectable describing the - * expected server identity, or %NULL if the expected identity is not - * known. - * Since: 2.28 - */ - - -/** - * g_tls_client_connection_get_use_ssl3: - * @conn: the #GTlsClientConnection - * - * SSL 3.0 is no longer supported. See - * g_tls_client_connection_set_use_ssl3() for details. - * - * Returns: %FALSE - * Since: 2.28 - * Deprecated: 2.56: SSL 3.0 is insecure. - */ - - -/** - * g_tls_client_connection_get_validation_flags: - * @conn: the #GTlsClientConnection - * - * Gets @conn's validation flags - * - * Returns: the validation flags - * Since: 2.28 - */ - - -/** - * g_tls_client_connection_new: - * @base_io_stream: the #GIOStream to wrap - * @server_identity: (nullable): the expected identity of the server - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a new #GTlsClientConnection wrapping @base_io_stream (which - * must have pollable input and output streams) which is assumed to - * communicate with the server identified by @server_identity. - * - * See the documentation for #GTlsConnection:base-io-stream for restrictions - * on when application code can run operations on the @base_io_stream after - * this function has returned. - * - * Returns: (transfer full) (type GTlsClientConnection): the new - * #GTlsClientConnection, or %NULL on error - * Since: 2.28 - */ - - -/** - * g_tls_client_connection_set_server_identity: - * @conn: the #GTlsClientConnection - * @identity: a #GSocketConnectable describing the expected server identity - * - * Sets @conn's expected server identity, which is used both to tell - * servers on virtual hosts which certificate to present, and also - * to let @conn know what name to look for in the certificate when - * performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. - * - * Since: 2.28 - */ - - -/** - * g_tls_client_connection_set_use_ssl3: - * @conn: the #GTlsClientConnection - * @use_ssl3: a #gboolean, ignored - * - * Since GLib 2.42.1, SSL 3.0 is no longer supported. - * - * From GLib 2.42.1 through GLib 2.62, this function could be used to - * force use of TLS 1.0, the lowest-supported TLS protocol version at - * the time. In the past, this was needed to connect to broken TLS - * servers that exhibited protocol version intolerance. Such servers - * are no longer common, and using TLS 1.0 is no longer considered - * acceptable. - * - * Since GLib 2.64, this function does nothing. - * - * Since: 2.28 - * Deprecated: 2.56: SSL 3.0 is insecure. - */ - - -/** - * g_tls_client_connection_set_validation_flags: - * @conn: the #GTlsClientConnection - * @flags: the #GTlsCertificateFlags to use - * - * Sets @conn's validation flags, to override the default set of - * checks performed when validating a server certificate. By default, - * %G_TLS_CERTIFICATE_VALIDATE_ALL is used. - * - * Since: 2.28 - */ - - -/** - * g_tls_connection_emit_accept_certificate: - * @conn: a #GTlsConnection - * @peer_cert: the peer's #GTlsCertificate - * @errors: the problems with @peer_cert - * - * Used by #GTlsConnection implementations to emit the - * #GTlsConnection::accept-certificate signal. - * - * Returns: %TRUE if one of the signal handlers has returned - * %TRUE to accept @peer_cert - * Since: 2.28 - */ - - -/** - * g_tls_connection_get_certificate: - * @conn: a #GTlsConnection - * - * Gets @conn's certificate, as set by - * g_tls_connection_set_certificate(). - * - * Returns: (transfer none) (nullable): @conn's certificate, or %NULL - * Since: 2.28 - */ - - -/** - * g_tls_connection_get_channel_binding_data: - * @conn: a #GTlsConnection - * @type: #GTlsChannelBindingType type of data to fetch - * @data: (out callee-allocates) (optional) (transfer none): #GByteArray is - * filled with the binding data, or %NULL - * @error: a #GError pointer, or %NULL - * - * Query the TLS backend for TLS channel binding data of @type for @conn. - * - * This call retrieves TLS channel binding data as specified in RFC - * [5056](https://tools.ietf.org/html/rfc5056), RFC - * [5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The - * binding data is returned in @data. The @data is resized by the callee - * using #GByteArray buffer management and will be freed when the @data - * is destroyed by g_byte_array_unref(). If @data is %NULL, it will only - * check whether TLS backend is able to fetch the data (e.g. whether @type - * is supported by the TLS backend). It does not guarantee that the data - * will be available though. That could happen if TLS connection does not - * support @type or the binding data is not available yet due to additional - * negotiation or input required. - * - * Returns: %TRUE on success, %FALSE otherwise - * Since: 2.66 - */ - - -/** - * g_tls_connection_get_ciphersuite_name: - * @conn: a #GTlsConnection - * - * Returns the name of the current TLS ciphersuite, or %NULL if the - * connection has not handshaked or has been closed. Beware that the TLS - * backend may use any of multiple different naming conventions, because - * OpenSSL and GnuTLS have their own ciphersuite naming conventions that - * are different from each other and different from the standard, IANA- - * registered ciphersuite names. The ciphersuite name is intended to be - * displayed to the user for informative purposes only, and parsing it - * is not recommended. - * - * Returns: (nullable): The name of the current TLS ciphersuite, or %NULL - * Since: 2.70 - */ - - -/** - * g_tls_connection_get_database: - * @conn: a #GTlsConnection - * - * Gets the certificate database that @conn uses to verify - * peer certificates. See g_tls_connection_set_database(). - * - * Returns: (transfer none) (nullable): the certificate database that @conn uses or %NULL - * Since: 2.30 - */ - - -/** - * g_tls_connection_get_interaction: - * @conn: a connection - * - * Get the object that will be used to interact with the user. It will be used - * for things like prompting the user for passwords. If %NULL is returned, then - * no user interaction will occur for this connection. - * - * Returns: (transfer none) (nullable): The interaction object. - * Since: 2.30 - */ - - -/** - * g_tls_connection_get_negotiated_protocol: - * @conn: a #GTlsConnection - * - * Gets the name of the application-layer protocol negotiated during - * the handshake. - * - * If the peer did not use the ALPN extension, or did not advertise a - * protocol that matched one of @conn's protocols, or the TLS backend - * does not support ALPN, then this will be %NULL. See - * g_tls_connection_set_advertised_protocols(). - * - * Returns: (nullable): the negotiated protocol, or %NULL - * Since: 2.60 - */ - - -/** - * g_tls_connection_get_peer_certificate: - * @conn: a #GTlsConnection - * - * Gets @conn's peer's certificate after the handshake has completed - * or failed. (It is not set during the emission of - * #GTlsConnection::accept-certificate.) - * - * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL - * Since: 2.28 - */ - - -/** - * g_tls_connection_get_peer_certificate_errors: - * @conn: a #GTlsConnection - * - * Gets the errors associated with validating @conn's peer's - * certificate, after the handshake has completed or failed. (It is - * not set during the emission of #GTlsConnection::accept-certificate.) - * - * Returns: @conn's peer's certificate errors - * Since: 2.28 - */ - - -/** - * g_tls_connection_get_protocol_version: - * @conn: a #GTlsConnection - * - * Returns the current TLS protocol version, which may be - * %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or - * has been closed, or if the TLS backend has implemented a protocol version - * that is not a recognized #GTlsProtocolVersion. - * - * Returns: The current TLS protocol version - * Since: 2.70 - */ - - -/** - * g_tls_connection_get_rehandshake_mode: - * @conn: a #GTlsConnection - * - * Gets @conn rehandshaking mode. See - * g_tls_connection_set_rehandshake_mode() for details. - * - * Returns: %G_TLS_REHANDSHAKE_SAFELY - * Since: 2.28 - * Deprecated: 2.60.: Changing the rehandshake mode is no longer - * required for compatibility. Also, rehandshaking has been removed - * from the TLS protocol in TLS 1.3. - */ - - -/** - * g_tls_connection_get_require_close_notify: - * @conn: a #GTlsConnection - * - * Tests whether or not @conn expects a proper TLS close notification - * when the connection is closed. See - * g_tls_connection_set_require_close_notify() for details. - * - * Returns: %TRUE if @conn requires a proper TLS close - * notification. - * Since: 2.28 - */ - - -/** - * g_tls_connection_get_use_system_certdb: - * @conn: a #GTlsConnection - * - * Gets whether @conn uses the system certificate database to verify - * peer certificates. See g_tls_connection_set_use_system_certdb(). - * - * Returns: whether @conn uses the system certificate database - * Deprecated: 2.30: Use g_tls_connection_get_database() instead - */ - - -/** - * g_tls_connection_handshake: - * @conn: a #GTlsConnection - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: a #GError, or %NULL - * - * Attempts a TLS handshake on @conn. - * - * On the client side, it is never necessary to call this method; - * although the connection needs to perform a handshake after - * connecting (or after sending a "STARTTLS"-type command), - * #GTlsConnection will handle this for you automatically when you try - * to send or receive data on the connection. You can call - * g_tls_connection_handshake() manually if you want to know whether - * the initial handshake succeeded or failed (as opposed to just - * immediately trying to use @conn to read or write, in which case, - * if it fails, it may not be possible to tell if it failed before or - * after completing the handshake), but beware that servers may reject - * client authentication after the handshake has completed, so a - * successful handshake does not indicate the connection will be usable. - * - * Likewise, on the server side, although a handshake is necessary at - * the beginning of the communication, you do not need to call this - * function explicitly unless you want clearer error reporting. - * - * Previously, calling g_tls_connection_handshake() after the initial - * handshake would trigger a rehandshake; however, this usage was - * deprecated in GLib 2.60 because rehandshaking was removed from the - * TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after - * the initial handshake will no longer do anything. - * - * When using a #GTlsConnection created by #GSocketClient, the - * #GSocketClient performs the initial handshake, so calling this - * function manually is not recommended. - * - * #GTlsConnection::accept_certificate may be emitted during the - * handshake. - * - * Returns: success or failure - * Since: 2.28 - */ - - -/** - * g_tls_connection_handshake_async: - * @conn: a #GTlsConnection - * @io_priority: the [I/O priority][io-priority] of the request - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the handshake is complete - * @user_data: the data to pass to the callback function - * - * Asynchronously performs a TLS handshake on @conn. See - * g_tls_connection_handshake() for more information. - * - * Since: 2.28 - */ - - -/** - * g_tls_connection_handshake_finish: - * @conn: a #GTlsConnection - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL - * - * Finish an asynchronous TLS handshake operation. See - * g_tls_connection_handshake() for more information. - * - * Returns: %TRUE on success, %FALSE on failure, in which - * case @error will be set. - * Since: 2.28 - */ - - -/** - * g_tls_connection_set_advertised_protocols: - * @conn: a #GTlsConnection - * @protocols: (array zero-terminated=1) (nullable): a %NULL-terminated - * array of ALPN protocol names (eg, "http/1.1", "h2"), or %NULL - * - * Sets the list of application-layer protocols to advertise that the - * caller is willing to speak on this connection. The - * Application-Layer Protocol Negotiation (ALPN) extension will be - * used to negotiate a compatible protocol with the peer; use - * g_tls_connection_get_negotiated_protocol() to find the negotiated - * protocol after the handshake. Specifying %NULL for the the value - * of @protocols will disable ALPN negotiation. - * - * See [IANA TLS ALPN Protocol IDs](https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) - * for a list of registered protocol IDs. - * - * Since: 2.60 - */ - - -/** - * g_tls_connection_set_certificate: - * @conn: a #GTlsConnection - * @certificate: the certificate to use for @conn - * - * This sets the certificate that @conn will present to its peer - * during the TLS handshake. For a #GTlsServerConnection, it is - * mandatory to set this, and that will normally be done at construct - * time. - * - * For a #GTlsClientConnection, this is optional. If a handshake fails - * with %G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server - * requires a certificate, and if you try connecting again, you should - * call this method first. You can call - * g_tls_client_connection_get_accepted_cas() on the failed connection - * to get a list of Certificate Authorities that the server will - * accept certificates from. - * - * (It is also possible that a server will allow the connection with - * or without a certificate; in that case, if you don't provide a - * certificate, you can tell that the server requested one by the fact - * that g_tls_client_connection_get_accepted_cas() will return - * non-%NULL.) - * - * Since: 2.28 - */ - - -/** - * g_tls_connection_set_database: - * @conn: a #GTlsConnection - * @database: (nullable): a #GTlsDatabase - * - * Sets the certificate database that is used to verify peer certificates. - * This is set to the default database by default. See - * g_tls_backend_get_default_database(). If set to %NULL, then - * peer certificate validation will always set the - * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning - * #GTlsConnection::accept-certificate will always be emitted on - * client-side connections, unless that bit is not set in - * #GTlsClientConnection:validation-flags). - * - * Since: 2.30 - */ - - -/** - * g_tls_connection_set_interaction: - * @conn: a connection - * @interaction: (nullable): an interaction object, or %NULL - * - * Set the object that will be used to interact with the user. It will be used - * for things like prompting the user for passwords. - * - * The @interaction argument will normally be a derived subclass of - * #GTlsInteraction. %NULL can also be provided if no user interaction - * should occur for this connection. - * - * Since: 2.30 - */ - - -/** - * g_tls_connection_set_rehandshake_mode: - * @conn: a #GTlsConnection - * @mode: the rehandshaking mode - * - * Since GLib 2.64, changing the rehandshake mode is no longer supported - * and will have no effect. With TLS 1.3, rehandshaking has been removed from - * the TLS protocol, replaced by separate post-handshake authentication and - * rekey operations. - * - * Since: 2.28 - * Deprecated: 2.60.: Changing the rehandshake mode is no longer - * required for compatibility. Also, rehandshaking has been removed - * from the TLS protocol in TLS 1.3. - */ - - -/** - * g_tls_connection_set_require_close_notify: - * @conn: a #GTlsConnection - * @require_close_notify: whether or not to require close notification - * - * Sets whether or not @conn expects a proper TLS close notification - * before the connection is closed. If this is %TRUE (the default), - * then @conn will expect to receive a TLS close notification from its - * peer before the connection is closed, and will return a - * %G_TLS_ERROR_EOF error if the connection is closed without proper - * notification (since this may indicate a network error, or - * man-in-the-middle attack). - * - * In some protocols, the application will know whether or not the - * connection was closed cleanly based on application-level data - * (because the application-level data includes a length field, or is - * somehow self-delimiting); in this case, the close notify is - * redundant and sometimes omitted. (TLS 1.1 explicitly allows this; - * in TLS 1.0 it is technically an error, but often done anyway.) You - * can use g_tls_connection_set_require_close_notify() to tell @conn - * to allow an "unannounced" connection close, in which case the close - * will show up as a 0-length read, as in a non-TLS - * #GSocketConnection, and it is up to the application to check that - * the data has been fully received. - * - * Note that this only affects the behavior when the peer closes the - * connection; when the application calls g_io_stream_close() itself - * on @conn, this will send a close notification regardless of the - * setting of this property. If you explicitly want to do an unclean - * close, you can close @conn's #GTlsConnection:base-io-stream rather - * than closing @conn itself, but note that this may only be done when no other - * operations are pending on @conn or the base I/O stream. - * - * Since: 2.28 - */ - - -/** - * g_tls_connection_set_use_system_certdb: - * @conn: a #GTlsConnection - * @use_system_certdb: whether to use the system certificate database - * - * Sets whether @conn uses the system certificate database to verify - * peer certificates. This is %TRUE by default. If set to %FALSE, then - * peer certificate validation will always set the - * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning - * #GTlsConnection::accept-certificate will always be emitted on - * client-side connections, unless that bit is not set in - * #GTlsClientConnection:validation-flags). - * - * Deprecated: 2.30: Use g_tls_connection_set_database() instead - */ - - -/** - * g_tls_database_create_certificate_handle: - * @self: a #GTlsDatabase - * @certificate: certificate for which to create a handle. - * - * Create a handle string for the certificate. The database will only be able - * to create a handle for certificates that originate from the database. In - * cases where the database cannot create a handle for a certificate, %NULL - * will be returned. - * - * This handle should be stable across various instances of the application, - * and between applications. If a certificate is modified in the database, - * then it is not guaranteed that this handle will continue to point to it. - * - * Returns: (nullable): a newly allocated string containing the - * handle. - * Since: 2.30 - */ - - -/** - * g_tls_database_lookup_certificate_for_handle: - * @self: a #GTlsDatabase - * @handle: a certificate handle - * @interaction: (nullable): used to interact with the user if necessary - * @flags: Flags which affect the lookup. - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: (nullable): a #GError, or %NULL - * - * Look up a certificate by its handle. - * - * The handle should have been created by calling - * g_tls_database_create_certificate_handle() on a #GTlsDatabase object of - * the same TLS backend. The handle is designed to remain valid across - * instantiations of the database. - * - * If the handle is no longer valid, or does not point to a certificate in - * this database, then %NULL will be returned. - * - * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform - * the lookup operation asynchronously. - * - * Returns: (transfer full) (nullable): a newly allocated - * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. - * Since: 2.30 - */ - - -/** - * g_tls_database_lookup_certificate_for_handle_async: - * @self: a #GTlsDatabase - * @handle: a certificate handle - * @interaction: (nullable): used to interact with the user if necessary - * @flags: Flags which affect the lookup. - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the operation completes - * @user_data: the data to pass to the callback function - * - * Asynchronously look up a certificate by its handle in the database. See - * g_tls_database_lookup_certificate_for_handle() for more information. - * - * Since: 2.30 - */ - - -/** - * g_tls_database_lookup_certificate_for_handle_finish: - * @self: a #GTlsDatabase - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL - * - * Finish an asynchronous lookup of a certificate by its handle. See - * g_tls_database_lookup_certificate_for_handle() for more information. - * - * If the handle is no longer valid, or does not point to a certificate in - * this database, then %NULL will be returned. - * - * Returns: (transfer full): a newly allocated #GTlsCertificate object. - * Use g_object_unref() to release the certificate. - * Since: 2.30 - */ - - -/** - * g_tls_database_lookup_certificate_issuer: - * @self: a #GTlsDatabase - * @certificate: a #GTlsCertificate - * @interaction: (nullable): used to interact with the user if necessary - * @flags: flags which affect the lookup operation - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: (nullable): a #GError, or %NULL - * - * Look up the issuer of @certificate in the database. The - * #GTlsCertificate:issuer property of @certificate is not modified, and - * the two certificates are not hooked into a chain. - * - * This function can block. Use g_tls_database_lookup_certificate_issuer_async() - * to perform the lookup operation asynchronously. - * - * Beware this function cannot be used to build certification paths. The - * issuer certificate returned by this function may not be the same as - * the certificate that would actually be used to construct a valid - * certification path during certificate verification. - * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains - * why an issuer certificate cannot be naively assumed to be part of the - * the certification path (though GLib's TLS backends may not follow the - * path building strategies outlined in this RFC). Due to the complexity - * of certification path building, GLib does not provide any way to know - * which certification path will actually be used when verifying a TLS - * certificate. Accordingly, this function cannot be used to make - * security-related decisions. Only GLib itself should make security - * decisions about TLS certificates. - * - * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, - * or %NULL. Use g_object_unref() to release the certificate. - * Since: 2.30 - */ - - -/** - * g_tls_database_lookup_certificate_issuer_async: - * @self: a #GTlsDatabase - * @certificate: a #GTlsCertificate - * @interaction: (nullable): used to interact with the user if necessary - * @flags: flags which affect the lookup operation - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the operation completes - * @user_data: the data to pass to the callback function - * - * Asynchronously look up the issuer of @certificate in the database. See - * g_tls_database_lookup_certificate_issuer() for more information. - * - * Since: 2.30 - */ - - -/** - * g_tls_database_lookup_certificate_issuer_finish: - * @self: a #GTlsDatabase - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL - * - * Finish an asynchronous lookup issuer operation. See - * g_tls_database_lookup_certificate_issuer() for more information. - * - * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, - * or %NULL. Use g_object_unref() to release the certificate. - * Since: 2.30 - */ - - -/** - * g_tls_database_lookup_certificates_issued_by: - * @self: a #GTlsDatabase - * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN. - * @interaction: (nullable): used to interact with the user if necessary - * @flags: Flags which affect the lookup operation. - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: (nullable): a #GError, or %NULL - * - * Look up certificates issued by this issuer in the database. - * - * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform - * the lookup operation asynchronously. - * - * 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 - */ - - -/** - * g_tls_database_lookup_certificates_issued_by_async: - * @self: a #GTlsDatabase - * @issuer_raw_dn: a #GByteArray which holds the DER encoded issuer DN. - * @interaction: (nullable): used to interact with the user if necessary - * @flags: Flags which affect the lookup operation. - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the operation completes - * @user_data: the data to pass to the callback function - * - * Asynchronously look up certificates issued by this issuer in the database. See - * g_tls_database_lookup_certificates_issued_by() for more information. - * - * The database may choose to hold a reference to the issuer byte array for the duration - * of of this asynchronous operation. The byte array should not be modified during - * this time. - * - * Since: 2.30 - */ - - -/** - * g_tls_database_lookup_certificates_issued_by_finish: - * @self: a #GTlsDatabase - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL - * - * Finish an asynchronous lookup of certificates. See - * g_tls_database_lookup_certificates_issued_by() for more information. - * - * 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 - */ - - -/** - * g_tls_database_verify_chain: - * @self: a #GTlsDatabase - * @chain: a #GTlsCertificate chain - * @purpose: the purpose that this certificate chain will be used for. - * @identity: (nullable): the expected peer identity - * @interaction: (nullable): used to interact with the user if necessary - * @flags: additional verify flags - * @cancellable: (nullable): a #GCancellable, or %NULL - * @error: (nullable): a #GError, or %NULL - * - * Determines the validity of a certificate chain, outside the context - * of a TLS session. - * - * @chain is a chain of #GTlsCertificate objects each pointing to the next - * certificate in the chain by its #GTlsCertificate:issuer property. - * - * @purpose describes the purpose (or usage) for which the certificate - * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER - * which means that the certificate is being used to authenticate a server - * (and we are acting as the client). - * - * The @identity is used to ensure the server certificate is valid for - * the expected peer identity. If the identity does not match the - * certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the - * return value. If @identity is %NULL, that bit will never be set in - * the return value. The peer identity may also be used to check for - * pinned certificates (trust exceptions) in the database. These may - * override the normal verification process on a host-by-host basis. - * - * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be - * used. - * - * If @chain is found to be valid, then the return value will be 0. If - * @chain is found to be invalid, then the return value will indicate - * the problems found. If the function is unable to determine whether - * @chain is valid or not (eg, because @cancellable is triggered - * before it completes) then the return value will be - * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set - * accordingly. @error is not set when @chain is successfully analyzed - * but found to be invalid. - * - * Prior to GLib 2.48, GLib's default TLS backend modified @chain to - * represent the certification path built by #GTlsDatabase during - * certificate verification by adjusting the #GTlsCertificate:issuer - * property of each certificate in @chain. Since GLib 2.48, this no - * longer occurs, so you cannot rely on #GTlsCertificate:issuer to - * represent the actual certification path used during certificate - * verification. - * - * Because TLS session context is not used, #GTlsDatabase may not - * perform as many checks on the certificates as #GTlsConnection would. - * For example, certificate constraints cannot be honored, and some - * revocation checks cannot be performed. The best way to verify TLS - * certificates used by a TLS connection is to let #GTlsConnection - * handle the verification. - * - * The TLS backend may attempt to look up and add missing certificates - * to the chain. Since GLib 2.70, this may involve HTTP requests to - * download missing certificates. - * - * This function can block. Use g_tls_database_verify_chain_async() to - * perform the verification operation asynchronously. - * - * Returns: the appropriate #GTlsCertificateFlags which represents the - * result of verification. - * Since: 2.30 - */ - - -/** - * g_tls_database_verify_chain_async: - * @self: a #GTlsDatabase - * @chain: a #GTlsCertificate chain - * @purpose: the purpose that this certificate chain will be used for. - * @identity: (nullable): the expected peer identity - * @interaction: (nullable): used to interact with the user if necessary - * @flags: additional verify flags - * @cancellable: (nullable): a #GCancellable, or %NULL - * @callback: callback to call when the operation completes - * @user_data: the data to pass to the callback function - * - * Asynchronously determines the validity of a certificate chain after - * looking up and adding any missing certificates to the chain. See - * g_tls_database_verify_chain() for more information. - * - * Since: 2.30 - */ - - -/** - * g_tls_database_verify_chain_finish: - * @self: a #GTlsDatabase - * @result: a #GAsyncResult. - * @error: a #GError pointer, or %NULL - * - * Finish an asynchronous verify chain operation. See - * g_tls_database_verify_chain() for more information. - * - * If @chain is found to be valid, then the return value will be 0. If - * @chain is found to be invalid, then the return value will indicate - * the problems found. If the function is unable to determine whether - * @chain is valid or not (eg, because @cancellable is triggered - * before it completes) then the return value will be - * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set - * accordingly. @error is not set when @chain is successfully analyzed - * but found to be invalid. - * - * Returns: the appropriate #GTlsCertificateFlags which represents the - * result of verification. - * Since: 2.30 - */ - - -/** - * g_tls_error_quark: - * - * Gets the TLS error quark. - * - * Returns: a #GQuark. - * Since: 2.28 - */ - - -/** - * g_tls_file_database_new: - * @anchors: (type filename): filename of anchor certificate authorities. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a new #GTlsFileDatabase which uses anchor certificate authorities - * in @anchors to verify certificate chains. - * - * The certificates in @anchors must be PEM encoded. - * - * Returns: (transfer full) (type GTlsFileDatabase): the new - * #GTlsFileDatabase, or %NULL on error - * Since: 2.30 - */ - - -/** - * g_tls_interaction_ask_password: - * @interaction: a #GTlsInteraction object - * @password: a #GTlsPassword object - * @cancellable: an optional #GCancellable cancellation object - * @error: an optional location to place an error on failure - * - * Run synchronous interaction to ask the user for a password. In general, - * g_tls_interaction_invoke_ask_password() should be used instead of this - * function. - * - * Derived subclasses usually implement a password prompt, although they may - * also choose to provide a password from elsewhere. The @password value will - * be filled in and then @callback will be called. Alternatively the user may - * abort this password request, which will usually abort the TLS connection. - * - * If the interaction is cancelled by the cancellation object, or by the - * user then %G_TLS_INTERACTION_FAILED will be returned with an error that - * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may - * not support immediate cancellation. - * - * Returns: The status of the ask password interaction. - * Since: 2.30 - */ - - -/** - * g_tls_interaction_ask_password_async: - * @interaction: a #GTlsInteraction object - * @password: a #GTlsPassword object - * @cancellable: an optional #GCancellable cancellation object - * @callback: (nullable): will be called when the interaction completes - * @user_data: (nullable): data to pass to the @callback - * - * Run asynchronous interaction to ask the user for a password. In general, - * g_tls_interaction_invoke_ask_password() should be used instead of this - * function. - * - * Derived subclasses usually implement a password prompt, although they may - * also choose to provide a password from elsewhere. The @password value will - * be filled in and then @callback will be called. Alternatively the user may - * abort this password request, which will usually abort the TLS connection. - * - * If the interaction is cancelled by the cancellation object, or by the - * user then %G_TLS_INTERACTION_FAILED will be returned with an error that - * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may - * not support immediate cancellation. - * - * Certain implementations may not support immediate cancellation. - * - * Since: 2.30 - */ - - -/** - * g_tls_interaction_ask_password_finish: - * @interaction: a #GTlsInteraction object - * @result: the result passed to the callback - * @error: an optional location to place an error on failure - * - * Complete an ask password user interaction request. This should be once - * the g_tls_interaction_ask_password_async() completion callback is called. - * - * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsPassword passed - * to g_tls_interaction_ask_password() will have its password filled in. - * - * If the interaction is cancelled by the cancellation object, or by the - * user then %G_TLS_INTERACTION_FAILED will be returned with an error that - * contains a %G_IO_ERROR_CANCELLED error code. - * - * Returns: The status of the ask password interaction. - * Since: 2.30 - */ - - -/** - * g_tls_interaction_invoke_ask_password: - * @interaction: a #GTlsInteraction object - * @password: a #GTlsPassword object - * @cancellable: an optional #GCancellable cancellation object - * @error: an optional location to place an error on failure - * - * Invoke the interaction to ask the user for a password. It invokes this - * interaction in the main loop, specifically the #GMainContext returned by - * g_main_context_get_thread_default() when the interaction is created. This - * is called by called by #GTlsConnection or #GTlsDatabase to ask the user - * for a password. - * - * Derived subclasses usually implement a password prompt, although they may - * also choose to provide a password from elsewhere. The @password value will - * be filled in and then @callback will be called. Alternatively the user may - * abort this password request, which will usually abort the TLS connection. - * - * The implementation can either be a synchronous (eg: modal dialog) or an - * asynchronous one (eg: modeless dialog). This function will take care of - * calling which ever one correctly. - * - * If the interaction is cancelled by the cancellation object, or by the - * user then %G_TLS_INTERACTION_FAILED will be returned with an error that - * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may - * not support immediate cancellation. - * - * Returns: The status of the ask password interaction. - * Since: 2.30 - */ - - -/** - * g_tls_interaction_invoke_request_certificate: - * @interaction: a #GTlsInteraction object - * @connection: a #GTlsConnection object - * @flags: flags providing more information about the request - * @cancellable: an optional #GCancellable cancellation object - * @error: an optional location to place an error on failure - * - * Invoke the interaction to ask the user to choose a certificate to - * use with the connection. It invokes this interaction in the main - * loop, specifically the #GMainContext returned by - * g_main_context_get_thread_default() when the interaction is - * created. This is called by called by #GTlsConnection when the peer - * requests a certificate during the handshake. - * - * Derived subclasses usually implement a certificate selector, - * although they may also choose to provide a certificate from - * elsewhere. Alternatively the user may abort this certificate - * request, which may or may not abort the TLS connection. - * - * The implementation can either be a synchronous (eg: modal dialog) or an - * asynchronous one (eg: modeless dialog). This function will take care of - * calling which ever one correctly. - * - * If the interaction is cancelled by the cancellation object, or by the - * user then %G_TLS_INTERACTION_FAILED will be returned with an error that - * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may - * not support immediate cancellation. - * - * Returns: The status of the certificate request interaction. - * Since: 2.40 - */ - - -/** - * g_tls_interaction_request_certificate: - * @interaction: a #GTlsInteraction object - * @connection: a #GTlsConnection object - * @flags: flags providing more information about the request - * @cancellable: an optional #GCancellable cancellation object - * @error: an optional location to place an error on failure - * - * Run synchronous interaction to ask the user to choose a certificate to use - * with the connection. In general, g_tls_interaction_invoke_request_certificate() - * should be used instead of this function. - * - * Derived subclasses usually implement a certificate selector, although they may - * also choose to provide a certificate from elsewhere. Alternatively the user may - * abort this certificate request, which will usually abort the TLS connection. - * - * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection - * passed to g_tls_interaction_request_certificate() will have had its - * #GTlsConnection:certificate filled in. - * - * If the interaction is cancelled by the cancellation object, or by the - * user then %G_TLS_INTERACTION_FAILED will be returned with an error that - * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may - * not support immediate cancellation. - * - * Returns: The status of the request certificate interaction. - * Since: 2.40 - */ - - -/** - * g_tls_interaction_request_certificate_async: - * @interaction: a #GTlsInteraction object - * @connection: a #GTlsConnection object - * @flags: flags providing more information about the request - * @cancellable: an optional #GCancellable cancellation object - * @callback: (nullable): will be called when the interaction completes - * @user_data: (nullable): data to pass to the @callback - * - * Run asynchronous interaction to ask the user for a certificate to use with - * the connection. In general, g_tls_interaction_invoke_request_certificate() should - * be used instead of this function. - * - * Derived subclasses usually implement a certificate selector, although they may - * also choose to provide a certificate from elsewhere. @callback will be called - * when the operation completes. Alternatively the user may abort this certificate - * request, which will usually abort the TLS connection. - * - * Since: 2.40 - */ - - -/** - * g_tls_interaction_request_certificate_finish: - * @interaction: a #GTlsInteraction object - * @result: the result passed to the callback - * @error: an optional location to place an error on failure - * - * Complete a request certificate user interaction request. This should be once - * the g_tls_interaction_request_certificate_async() completion callback is called. - * - * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection - * passed to g_tls_interaction_request_certificate_async() will have had its - * #GTlsConnection:certificate filled in. - * - * If the interaction is cancelled by the cancellation object, or by the - * user then %G_TLS_INTERACTION_FAILED will be returned with an error that - * contains a %G_IO_ERROR_CANCELLED error code. - * - * Returns: The status of the request certificate interaction. - * Since: 2.40 - */ - - -/** - * g_tls_password_get_description: - * @password: a #GTlsPassword object - * - * Get a description string about what the password will be used for. - * - * Returns: The description of the password. - * Since: 2.30 - */ - - -/** - * g_tls_password_get_flags: - * @password: a #GTlsPassword object - * - * Get flags about the password. - * - * Returns: The flags about the password. - * Since: 2.30 - */ - - -/** - * g_tls_password_get_value: (virtual get_value) - * @password: a #GTlsPassword object - * @length: (optional): location to place the length of the password. - * - * Get the password value. If @length is not %NULL then it will be - * filled in with the length of the password value. (Note that the - * password value is not nul-terminated, so you can only pass %NULL - * for @length in contexts where you know the password will have a - * certain fixed length.) - * - * Returns: (array length=length): The password value (owned by the password object). - * Since: 2.30 - */ - - -/** - * g_tls_password_get_warning: - * @password: a #GTlsPassword object - * - * Get a user readable translated warning. Usually this warning is a - * representation of the password flags returned from - * g_tls_password_get_flags(). - * - * Returns: The warning. - * Since: 2.30 - */ - - -/** - * g_tls_password_new: - * @flags: the password flags - * @description: description of what the password is for - * - * Create a new #GTlsPassword object. - * - * Returns: (transfer full): The newly allocated password object - */ - - -/** - * g_tls_password_set_description: - * @password: a #GTlsPassword object - * @description: The description of the password - * - * Set a description string about what the password will be used for. - * - * Since: 2.30 - */ - - -/** - * g_tls_password_set_flags: - * @password: a #GTlsPassword object - * @flags: The flags about the password - * - * Set flags about the password. - * - * Since: 2.30 - */ - - -/** - * g_tls_password_set_value: - * @password: a #GTlsPassword object - * @value: (array length=length): the new password value - * @length: the length of the password, or -1 - * - * Set the value for this password. The @value will be copied by the password - * object. - * - * Specify the @length, for a non-nul-terminated password. Pass -1 as - * @length if using a nul-terminated password, and @length will be - * calculated automatically. (Note that the terminating nul is not - * considered part of the password in this case.) - * - * Since: 2.30 - */ - - -/** - * g_tls_password_set_value_full: (virtual set_value) - * @password: a #GTlsPassword object - * @value: (array length=length): the value for the password - * @length: the length of the password, or -1 - * @destroy: (nullable): a function to use to free the password. - * - * Provide the value for this password. - * - * The @value will be owned by the password object, and later freed using - * the @destroy function callback. - * - * Specify the @length, for a non-nul-terminated password. Pass -1 as - * @length if using a nul-terminated password, and @length will be - * calculated automatically. (Note that the terminating nul is not - * considered part of the password in this case.) - * - * Since: 2.30 - */ - - -/** - * g_tls_password_set_warning: - * @password: a #GTlsPassword object - * @warning: The user readable warning - * - * Set a user readable translated warning. Usually this warning is a - * representation of the password flags returned from - * g_tls_password_get_flags(). - * - * Since: 2.30 - */ - - -/** - * g_tls_server_connection_new: - * @base_io_stream: the #GIOStream to wrap - * @certificate: (nullable): the default server certificate, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Creates a new #GTlsServerConnection wrapping @base_io_stream (which - * must have pollable input and output streams). - * - * See the documentation for #GTlsConnection:base-io-stream for restrictions - * on when application code can run operations on the @base_io_stream after - * this function has returned. - * - * Returns: (transfer full) (type GTlsServerConnection): the new - * #GTlsServerConnection, or %NULL on error - * Since: 2.28 - */ - - -/** - * g_unix_connection_receive_credentials: - * @connection: A #GUnixConnection. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Receives credentials from the sending end of the connection. The - * sending end has to call g_unix_connection_send_credentials() (or - * similar) for this to work. - * - * As well as reading the credentials this also reads (and discards) a - * single byte from the stream, as this is required for credentials - * passing to work on some implementations. - * - * This method can be expected to be available on the following platforms: - * - * - Linux since GLib 2.26 - * - FreeBSD since GLib 2.26 - * - GNU/kFreeBSD since GLib 2.36 - * - Solaris, Illumos and OpenSolaris since GLib 2.40 - * - GNU/Hurd since GLib 2.40 - * - * Other ways to exchange credentials with a foreign peer includes the - * #GUnixCredentialsMessage type and g_socket_get_credentials() function. - * - * Returns: (transfer full): Received credentials on success (free with - * g_object_unref()), %NULL if @error is set. - * Since: 2.26 - */ - - -/** - * g_unix_connection_receive_credentials_async: - * @connection: A #GUnixConnection. - * @cancellable: (nullable): 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 - * - * Asynchronously receive credentials. - * - * For more details, see g_unix_connection_receive_credentials() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. You can then call - * g_unix_connection_receive_credentials_finish() to get the result of the operation. - * - * Since: 2.32 - */ - - -/** - * g_unix_connection_receive_credentials_finish: - * @connection: A #GUnixConnection. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes an asynchronous receive credentials operation started with - * g_unix_connection_receive_credentials_async(). - * - * Returns: (transfer full): a #GCredentials, or %NULL on error. - * Free the returned object with g_object_unref(). - * Since: 2.32 - */ - - -/** - * g_unix_connection_receive_fd: - * @connection: a #GUnixConnection - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @error: (nullable): #GError for error reporting, or %NULL to ignore - * - * Receives a file descriptor from the sending end of the connection. - * The sending end has to call g_unix_connection_send_fd() for this - * to work. - * - * As well as reading the fd this also reads a single byte from the - * stream, as this is required for fd passing to work on some - * implementations. - * - * Returns: a file descriptor on success, -1 on error. - * Since: 2.22 - */ - - -/** - * g_unix_connection_send_credentials: - * @connection: A #GUnixConnection. - * @cancellable: (nullable): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. - * - * Passes the credentials of the current user the receiving side - * of the connection. The receiving end has to call - * g_unix_connection_receive_credentials() (or similar) to accept the - * credentials. - * - * As well as sending the credentials this also writes a single NUL - * byte to the stream, as this is required for credentials passing to - * work on some implementations. - * - * This method can be expected to be available on the following platforms: - * - * - Linux since GLib 2.26 - * - FreeBSD since GLib 2.26 - * - GNU/kFreeBSD since GLib 2.36 - * - Solaris, Illumos and OpenSolaris since GLib 2.40 - * - GNU/Hurd since GLib 2.40 - * - * Other ways to exchange credentials with a foreign peer includes the - * #GUnixCredentialsMessage type and g_socket_get_credentials() function. - * - * Returns: %TRUE on success, %FALSE if @error is set. - * Since: 2.26 - */ - - -/** - * g_unix_connection_send_credentials_async: - * @connection: A #GUnixConnection. - * @cancellable: (nullable): 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 - * - * Asynchronously send credentials. - * - * For more details, see g_unix_connection_send_credentials() which is - * the synchronous version of this call. - * - * When the operation is finished, @callback will be called. You can then call - * g_unix_connection_send_credentials_finish() to get the result of the operation. - * - * Since: 2.32 - */ - - -/** - * g_unix_connection_send_credentials_finish: - * @connection: A #GUnixConnection. - * @result: a #GAsyncResult. - * @error: a #GError, or %NULL - * - * Finishes an asynchronous send credentials operation started with - * g_unix_connection_send_credentials_async(). - * - * Returns: %TRUE if the operation was successful, otherwise %FALSE. - * Since: 2.32 - */ - - -/** - * g_unix_connection_send_fd: - * @connection: a #GUnixConnection - * @fd: a file descriptor - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. - * @error: (nullable): #GError for error reporting, or %NULL to ignore. - * - * Passes a file descriptor to the receiving side of the - * connection. The receiving end has to call g_unix_connection_receive_fd() - * to accept the file descriptor. - * - * As well as sending the fd this also writes a single byte to the - * stream, as this is required for fd passing to work on some - * implementations. - * - * Returns: a %TRUE on success, %NULL on error. - * Since: 2.22 - */ - - -/** - * g_unix_credentials_message_get_credentials: - * @message: A #GUnixCredentialsMessage. - * - * Gets the credentials stored in @message. - * - * Returns: (transfer none): A #GCredentials instance. Do not free, it is owned by @message. - * Since: 2.26 - */ - - -/** - * g_unix_credentials_message_is_supported: - * - * Checks if passing #GCredentials on a #GSocket is supported on this platform. - * - * Returns: %TRUE if supported, %FALSE otherwise - * Since: 2.26 - */ - - -/** - * g_unix_credentials_message_new: - * - * Creates a new #GUnixCredentialsMessage with credentials matching the current processes. - * - * Returns: a new #GUnixCredentialsMessage - * Since: 2.26 - */ - - -/** - * g_unix_credentials_message_new_with_credentials: - * @credentials: A #GCredentials object. - * - * Creates a new #GUnixCredentialsMessage holding @credentials. - * - * Returns: a new #GUnixCredentialsMessage - * Since: 2.26 - */ - - -/** - * g_unix_fd_list_append: - * @list: a #GUnixFDList - * @fd: a valid open file descriptor - * @error: a #GError pointer - * - * Adds a file descriptor to @list. - * - * The file descriptor is duplicated using dup(). You keep your copy - * of the descriptor and the copy contained in @list will be closed - * when @list is finalized. - * - * A possible cause of failure is exceeding the per-process or - * system-wide file descriptor limit. - * - * The index of the file descriptor in the list is returned. If you use - * this index with g_unix_fd_list_get() then you will receive back a - * duplicated copy of the same file descriptor. - * - * Returns: the index of the appended fd in case of success, else -1 - * (and @error is set) - * Since: 2.24 - */ - - -/** - * g_unix_fd_list_get: - * @list: a #GUnixFDList - * @index_: the index into the list - * @error: a #GError pointer - * - * Gets a file descriptor out of @list. - * - * @index_ specifies the index of the file descriptor to get. It is a - * programmer error for @index_ to be out of range; see - * g_unix_fd_list_get_length(). - * - * The file descriptor is duplicated using dup() and set as - * close-on-exec before being returned. You must call close() on it - * when you are done. - * - * A possible cause of failure is exceeding the per-process or - * system-wide file descriptor limit. - * - * Returns: the file descriptor, or -1 in case of error - * Since: 2.24 - */ - - -/** - * g_unix_fd_list_get_length: - * @list: a #GUnixFDList - * - * Gets the length of @list (ie: the number of file descriptors - * contained within). - * - * Returns: the length of @list - * Since: 2.24 - */ - - -/** - * g_unix_fd_list_new: - * - * Creates a new #GUnixFDList containing no file descriptors. - * - * Returns: a new #GUnixFDList - * Since: 2.24 - */ - - -/** - * g_unix_fd_list_new_from_array: - * @fds: (array length=n_fds): the initial list of file descriptors - * @n_fds: the length of #fds, or -1 - * - * Creates a new #GUnixFDList containing the file descriptors given in - * @fds. The file descriptors become the property of the new list and - * may no longer be used by the caller. The array itself is owned by - * the caller. - * - * Each file descriptor in the array should be set to close-on-exec. - * - * If @n_fds is -1 then @fds must be terminated with -1. - * - * Returns: a new #GUnixFDList - * Since: 2.24 - */ - - -/** - * g_unix_fd_list_peek_fds: - * @list: a #GUnixFDList - * @length: (out) (optional): pointer to the length of the returned - * array, or %NULL - * - * Returns the array of file descriptors that is contained in this - * object. - * - * After this call, the descriptors remain the property of @list. The - * caller must not close them and must not free the array. The array is - * valid only until @list is changed in any way. - * - * If @length is non-%NULL then it is set to the number of file - * descriptors in the returned array. The returned array is also - * terminated with -1. - * - * This function never returns %NULL. In case there are no file - * descriptors contained in @list, an empty array is returned. - * - * Returns: (array length=length) (transfer none): an array of file - * descriptors - * Since: 2.24 - */ - - -/** - * g_unix_fd_list_steal_fds: - * @list: a #GUnixFDList - * @length: (out) (optional): pointer to the length of the returned - * array, or %NULL - * - * Returns the array of file descriptors that is contained in this - * object. - * - * After this call, the descriptors are no longer contained in - * @list. Further calls will return an empty list (unless more - * descriptors have been added). - * - * The return result of this function must be freed with g_free(). - * The caller is also responsible for closing all of the file - * descriptors. The file descriptors in the array are set to - * close-on-exec. - * - * If @length is non-%NULL then it is set to the number of file - * descriptors in the returned array. The returned array is also - * terminated with -1. - * - * This function never returns %NULL. In case there are no file - * descriptors contained in @list, an empty array is returned. - * - * Returns: (array length=length) (transfer full): an array of file - * descriptors - * Since: 2.24 - */ - - -/** - * g_unix_fd_message_append_fd: - * @message: a #GUnixFDMessage - * @fd: a valid open file descriptor - * @error: a #GError pointer - * - * Adds a file descriptor to @message. - * - * The file descriptor is duplicated using dup(). You keep your copy - * of the descriptor and the copy contained in @message will be closed - * when @message is finalized. - * - * A possible cause of failure is exceeding the per-process or - * system-wide file descriptor limit. - * - * Returns: %TRUE in case of success, else %FALSE (and @error is set) - * Since: 2.22 - */ - - -/** - * g_unix_fd_message_get_fd_list: - * @message: a #GUnixFDMessage - * - * Gets the #GUnixFDList contained in @message. This function does not - * return a reference to the caller, but the returned list is valid for - * the lifetime of @message. - * - * Returns: (transfer none): the #GUnixFDList from @message - * Since: 2.24 - */ - - -/** - * g_unix_fd_message_new: - * - * Creates a new #GUnixFDMessage containing an empty file descriptor - * list. - * - * Returns: a new #GUnixFDMessage - * Since: 2.22 - */ - - -/** - * g_unix_fd_message_new_with_fd_list: - * @fd_list: a #GUnixFDList - * - * Creates a new #GUnixFDMessage containing @list. - * - * Returns: a new #GUnixFDMessage - * Since: 2.24 - */ - - -/** - * g_unix_fd_message_steal_fds: - * @message: a #GUnixFDMessage - * @length: (out) (optional): pointer to the length of the returned - * array, or %NULL - * - * Returns the array of file descriptors that is contained in this - * object. - * - * After this call, the descriptors are no longer contained in - * @message. Further calls will return an empty list (unless more - * descriptors have been added). - * - * The return result of this function must be freed with g_free(). - * The caller is also responsible for closing all of the file - * descriptors. - * - * If @length is non-%NULL then it is set to the number of file - * descriptors in the returned array. The returned array is also - * terminated with -1. - * - * This function never returns %NULL. In case there are no file - * descriptors contained in @message, an empty array is returned. - * - * Returns: (array length=length) (transfer full): an array of file - * descriptors - * Since: 2.22 - */ - - -/** - * g_unix_input_stream_get_close_fd: - * @stream: a #GUnixInputStream - * - * Returns whether the file descriptor of @stream will be - * closed when the stream is closed. - * - * Returns: %TRUE if the file descriptor is closed when done - * Since: 2.20 - */ - - -/** - * g_unix_input_stream_get_fd: - * @stream: a #GUnixInputStream - * - * Return the UNIX file descriptor that the stream reads from. - * - * Returns: The file descriptor of @stream - * Since: 2.20 - */ - - -/** - * g_unix_input_stream_new: - * @fd: a UNIX file descriptor - * @close_fd: %TRUE to close the file descriptor when done - * - * Creates a new #GUnixInputStream for the given @fd. - * - * If @close_fd is %TRUE, the file descriptor will be closed - * when the stream is closed. - * - * Returns: a new #GUnixInputStream - */ - - -/** - * g_unix_input_stream_set_close_fd: - * @stream: a #GUnixInputStream - * @close_fd: %TRUE to close the file descriptor when done - * - * Sets whether the file descriptor of @stream shall be closed - * when the stream is closed. - * - * Since: 2.20 - */ - - -/** - * g_unix_is_mount_path_system_internal: - * @mount_path: (type filename): a mount path, e.g. `/media/disk` or `/usr` - * - * Determines if @mount_path is considered an implementation of the - * OS. This is primarily used for hiding mountable and mounted volumes - * that only are used in the OS and has little to no relevance to the - * casual user. - * - * Returns: %TRUE if @mount_path is considered an implementation detail - * of the OS. - */ - - -/** - * g_unix_is_system_device_path: - * @device_path: a device path, e.g. `/dev/loop0` or `nfsd` - * - * Determines if @device_path is considered a block device path which is only - * used in implementation of the OS. This is primarily used for hiding - * mounted volumes that are intended as APIs for programs to read, and system - * administrators at a shell; rather than something that should, for example, - * appear in a GUI. For example, the Linux `/proc` filesystem. - * - * The list of device paths considered ‘system’ ones may change over time. - * - * Returns: %TRUE if @device_path is considered an implementation detail of - * the OS. - * Since: 2.56 - */ - - -/** - * g_unix_is_system_fs_type: - * @fs_type: a file system type, e.g. `procfs` or `tmpfs` - * - * Determines if @fs_type is considered a type of file system which is only - * used in implementation of the OS. This is primarily used for hiding - * mounted volumes that are intended as APIs for programs to read, and system - * administrators at a shell; rather than something that should, for example, - * appear in a GUI. For example, the Linux `/proc` filesystem. - * - * The list of file system types considered ‘system’ ones may change over time. - * - * Returns: %TRUE if @fs_type is considered an implementation detail of the OS. - * Since: 2.56 - */ - - -/** - * g_unix_mount_at: - * @mount_path: (type filename): path for a possible unix mount. - * @time_read: (out) (optional): guint64 to contain a timestamp. - * - * Gets a #GUnixMountEntry for a given mount path. If @time_read - * is set, it will be filled with a unix timestamp for checking - * if the mounts have changed since with g_unix_mounts_changed_since(). - * - * If more mounts have the same mount path, the last matching mount - * is returned. - * - * This will return %NULL if there is no mount point at @mount_path. - * - * Returns: (transfer full) (nullable): a #GUnixMountEntry. - */ - - -/** - * g_unix_mount_compare: - * @mount1: first #GUnixMountEntry to compare. - * @mount2: second #GUnixMountEntry to compare. - * - * Compares two unix mounts. - * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, - * or less than @mount2, respectively. - */ - - -/** - * g_unix_mount_copy: - * @mount_entry: a #GUnixMountEntry. - * - * Makes a copy of @mount_entry. - * - * Returns: (transfer full): a new #GUnixMountEntry - * Since: 2.54 - */ - - -/** - * g_unix_mount_for: - * @file_path: (type filename): file path on some unix mount. - * @time_read: (out) (optional): guint64 to contain a timestamp. - * - * Gets a #GUnixMountEntry for a given file path. If @time_read - * is set, it will be filled with a unix timestamp for checking - * if the mounts have changed since with g_unix_mounts_changed_since(). - * - * If more mounts have the same mount path, the last matching mount - * is returned. - * - * This will return %NULL if looking up the mount entry fails, if - * @file_path doesn’t exist or there is an I/O error. - * - * Returns: (transfer full) (nullable): a #GUnixMountEntry. - * Since: 2.52 - */ - - -/** - * g_unix_mount_free: - * @mount_entry: a #GUnixMountEntry. - * - * Frees a unix mount. - */ - - -/** - * g_unix_mount_get_device_path: - * @mount_entry: a #GUnixMount. - * - * Gets the device path for a unix mount. - * - * Returns: (type filename): a string containing the device path. - */ - - -/** - * g_unix_mount_get_fs_type: - * @mount_entry: a #GUnixMount. - * - * Gets the filesystem type for the unix mount. - * - * Returns: a string containing the file system type. - */ - - -/** - * g_unix_mount_get_mount_path: - * @mount_entry: input #GUnixMountEntry to get the mount path for. - * - * Gets the mount path for a unix mount. - * - * Returns: (type filename): the mount path for @mount_entry. - */ - - -/** - * g_unix_mount_get_options: - * @mount_entry: a #GUnixMountEntry. - * - * Gets a comma-separated list of mount options for the unix mount. For example, - * `rw,relatime,seclabel,data=ordered`. - * - * This is similar to g_unix_mount_point_get_options(), but it takes - * a #GUnixMountEntry as an argument. - * - * Returns: (nullable): a string containing the options, or %NULL if not - * available. - * Since: 2.58 - */ - - -/** - * g_unix_mount_get_root_path: - * @mount_entry: a #GUnixMountEntry. - * - * Gets the root of the mount within the filesystem. This is useful e.g. for - * mounts created by bind operation, or btrfs subvolumes. - * - * For example, the root path is equal to "/" for mount created by - * "mount /dev/sda1 /mnt/foo" and "/bar" for - * "mount --bind /mnt/foo/bar /mnt/bar". - * - * Returns: (nullable): a string containing the root, or %NULL if not supported. - * Since: 2.60 - */ - - -/** - * g_unix_mount_guess_can_eject: - * @mount_entry: a #GUnixMountEntry - * - * Guesses whether a Unix mount can be ejected. - * - * Returns: %TRUE if @mount_entry is deemed to be ejectable. - */ - - -/** - * g_unix_mount_guess_icon: - * @mount_entry: a #GUnixMountEntry - * - * Guesses the icon of a Unix mount. - * - * Returns: (transfer full): a #GIcon - */ - - -/** - * g_unix_mount_guess_name: - * @mount_entry: a #GUnixMountEntry - * - * Guesses the name of a Unix mount. - * The result is a translated string. - * - * Returns: A newly allocated string that must - * be freed with g_free() - */ - - -/** - * g_unix_mount_guess_should_display: - * @mount_entry: a #GUnixMountEntry - * - * Guesses whether a Unix mount should be displayed in the UI. - * - * Returns: %TRUE if @mount_entry is deemed to be displayable. - */ - - -/** - * g_unix_mount_guess_symbolic_icon: - * @mount_entry: a #GUnixMountEntry - * - * Guesses the symbolic icon of a Unix mount. - * - * Returns: (transfer full): a #GIcon - * Since: 2.34 - */ - - -/** - * g_unix_mount_guess_type: - * @mount_entry: a #GUnixMount. - * - * Guesses the type of a unix mount. If the mount type cannot be - * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN. - * - * Returns: a #GUnixMountType. - */ - - -/** - * g_unix_mount_is_readonly: - * @mount_entry: a #GUnixMount. - * - * Checks if a unix mount is mounted read only. - * - * Returns: %TRUE if @mount_entry is read only. - */ - - -/** - * g_unix_mount_is_system_internal: - * @mount_entry: a #GUnixMount. - * - * Checks if a Unix mount is a system mount. This is the Boolean OR of - * g_unix_is_system_fs_type(), g_unix_is_system_device_path() and - * g_unix_is_mount_path_system_internal() on @mount_entry’s properties. - * - * The definition of what a ‘system’ mount entry is may change over time as new - * file system types and device paths are ignored. - * - * Returns: %TRUE if the unix mount is for a system path. - */ - - -/** - * g_unix_mount_monitor_get: - * - * Gets the #GUnixMountMonitor for the current thread-default main - * context. - * - * The mount monitor can be used to monitor for changes to the list of - * mounted filesystems as well as the list of mount points (ie: fstab - * entries). - * - * You must only call g_object_unref() on the return value from under - * the same main context as you called this function. - * - * Returns: (transfer full): the #GUnixMountMonitor. - * Since: 2.44 - */ - - -/** - * g_unix_mount_monitor_new: - * - * Deprecated alias for g_unix_mount_monitor_get(). - * - * This function was never a true constructor, which is why it was - * renamed. - * - * Returns: a #GUnixMountMonitor. - * Deprecated: 2.44: Use g_unix_mount_monitor_get() instead. - */ - - -/** - * g_unix_mount_monitor_set_rate_limit: - * @mount_monitor: a #GUnixMountMonitor - * @limit_msec: a integer with the limit in milliseconds to - * poll for changes. - * - * This function does nothing. - * - * Before 2.44, this was a partially-effective way of controlling the - * rate at which events would be reported under some uncommon - * circumstances. Since @mount_monitor is a singleton, it also meant - * that calling this function would have side effects for other users of - * the monitor. - * - * Since: 2.18 - * Deprecated: 2.44: This function does nothing. Don't call it. - */ - - -/** - * g_unix_mount_point_at: - * @mount_path: (type filename): path for a possible unix mount point. - * @time_read: (out) (optional): guint64 to contain a timestamp. - * - * Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it - * will be filled with a unix timestamp for checking if the mount points have - * changed since with g_unix_mount_points_changed_since(). - * - * If more mount points have the same mount path, the last matching mount point - * is returned. - * - * Returns: (transfer full) (nullable): a #GUnixMountPoint, or %NULL if no match - * is found. - * Since: 2.66 - */ - - -/** - * g_unix_mount_point_compare: - * @mount1: a #GUnixMount. - * @mount2: a #GUnixMount. - * - * Compares two unix mount points. - * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, - * or less than @mount2, respectively. - */ - - -/** - * g_unix_mount_point_copy: - * @mount_point: a #GUnixMountPoint. - * - * Makes a copy of @mount_point. - * - * Returns: (transfer full): a new #GUnixMountPoint - * Since: 2.54 - */ - - -/** - * g_unix_mount_point_free: - * @mount_point: unix mount point to free. - * - * Frees a unix mount point. - */ - - -/** - * g_unix_mount_point_get_device_path: - * @mount_point: a #GUnixMountPoint. - * - * Gets the device path for a unix mount point. - * - * Returns: (type filename): a string containing the device path. - */ - - -/** - * g_unix_mount_point_get_fs_type: - * @mount_point: a #GUnixMountPoint. - * - * Gets the file system type for the mount point. - * - * Returns: a string containing the file system type. - */ - - -/** - * g_unix_mount_point_get_mount_path: - * @mount_point: a #GUnixMountPoint. - * - * Gets the mount path for a unix mount point. - * - * Returns: (type filename): a string containing the mount path. - */ - - -/** - * g_unix_mount_point_get_options: - * @mount_point: a #GUnixMountPoint. - * - * Gets the options for the mount point. - * - * Returns: (nullable): a string containing the options. - * Since: 2.32 - */ - - -/** - * g_unix_mount_point_guess_can_eject: - * @mount_point: a #GUnixMountPoint - * - * Guesses whether a Unix mount point can be ejected. - * - * Returns: %TRUE if @mount_point is deemed to be ejectable. - */ - - -/** - * g_unix_mount_point_guess_icon: - * @mount_point: a #GUnixMountPoint - * - * Guesses the icon of a Unix mount point. - * - * Returns: (transfer full): a #GIcon - */ - - -/** - * g_unix_mount_point_guess_name: - * @mount_point: a #GUnixMountPoint - * - * Guesses the name of a Unix mount point. - * The result is a translated string. - * - * Returns: A newly allocated string that must - * be freed with g_free() - */ - - -/** - * g_unix_mount_point_guess_symbolic_icon: - * @mount_point: a #GUnixMountPoint - * - * Guesses the symbolic icon of a Unix mount point. - * - * Returns: (transfer full): a #GIcon - * Since: 2.34 - */ - - -/** - * g_unix_mount_point_guess_type: - * @mount_point: a #GUnixMountPoint. - * - * Guesses the type of a unix mount point. - * If the mount type cannot be determined, - * returns %G_UNIX_MOUNT_TYPE_UNKNOWN. - * - * Returns: a #GUnixMountType. - */ - - -/** - * g_unix_mount_point_is_loopback: - * @mount_point: a #GUnixMountPoint. - * - * Checks if a unix mount point is a loopback device. - * - * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise. - */ - - -/** - * g_unix_mount_point_is_readonly: - * @mount_point: a #GUnixMountPoint. - * - * Checks if a unix mount point is read only. - * - * Returns: %TRUE if a mount point is read only. - */ - - -/** - * g_unix_mount_point_is_user_mountable: - * @mount_point: a #GUnixMountPoint. - * - * Checks if a unix mount point is mountable by the user. - * - * Returns: %TRUE if the mount point is user mountable. - */ - - -/** - * g_unix_mount_points_changed_since: - * @time: guint64 to contain a timestamp. - * - * Checks if the unix mount points have changed since a given unix time. - * - * Returns: %TRUE if the mount points have changed since @time. - */ - - -/** - * g_unix_mount_points_get: - * @time_read: (out) (optional): guint64 to contain a timestamp. - * - * Gets a #GList of #GUnixMountPoint containing the unix mount points. - * If @time_read is set, it will be filled with the mount timestamp, - * allowing for checking if the mounts have changed with - * g_unix_mount_points_changed_since(). - * - * Returns: (element-type GUnixMountPoint) (transfer full): - * a #GList of the UNIX mountpoints. - */ - - -/** - * g_unix_mounts_changed_since: - * @time: guint64 to contain a timestamp. - * - * Checks if the unix mounts have changed since a given unix time. - * - * Returns: %TRUE if the mounts have changed since @time. - */ - - -/** - * g_unix_mounts_get: - * @time_read: (out) (optional): guint64 to contain a timestamp, or %NULL - * - * Gets a #GList of #GUnixMountEntry containing the unix mounts. - * If @time_read is set, it will be filled with the mount - * timestamp, allowing for checking if the mounts have changed - * with g_unix_mounts_changed_since(). - * - * Returns: (element-type GUnixMountEntry) (transfer full): - * a #GList of the UNIX mounts. - */ - - -/** - * g_unix_output_stream_get_close_fd: - * @stream: a #GUnixOutputStream - * - * Returns whether the file descriptor of @stream will be - * closed when the stream is closed. - * - * Returns: %TRUE if the file descriptor is closed when done - * Since: 2.20 - */ - - -/** - * g_unix_output_stream_get_fd: - * @stream: a #GUnixOutputStream - * - * Return the UNIX file descriptor that the stream writes to. - * - * Returns: The file descriptor of @stream - * Since: 2.20 - */ - - -/** - * g_unix_output_stream_new: - * @fd: a UNIX file descriptor - * @close_fd: %TRUE to close the file descriptor when done - * - * Creates a new #GUnixOutputStream for the given @fd. - * - * If @close_fd, is %TRUE, the file descriptor will be closed when - * the output stream is destroyed. - * - * Returns: a new #GOutputStream - */ - - -/** - * g_unix_output_stream_set_close_fd: - * @stream: a #GUnixOutputStream - * @close_fd: %TRUE to close the file descriptor when done - * - * Sets whether the file descriptor of @stream shall be closed - * when the stream is closed. - * - * Since: 2.20 - */ - - -/** - * g_unix_socket_address_abstract_names_supported: - * - * Checks if abstract UNIX domain socket names are supported. - * - * Returns: %TRUE if supported, %FALSE otherwise - * Since: 2.22 - */ - - -/** - * g_unix_socket_address_get_address_type: - * @address: a #GInetSocketAddress - * - * Gets @address's type. - * - * Returns: a #GUnixSocketAddressType - * Since: 2.26 - */ - - -/** - * g_unix_socket_address_get_is_abstract: - * @address: a #GInetSocketAddress - * - * Tests if @address is abstract. - * - * Returns: %TRUE if the address is abstract, %FALSE otherwise - * Since: 2.22 - * Deprecated: Use g_unix_socket_address_get_address_type() - */ - - -/** - * g_unix_socket_address_get_path: - * @address: a #GInetSocketAddress - * - * Gets @address's path, or for abstract sockets the "name". - * - * Guaranteed to be zero-terminated, but an abstract socket - * may contain embedded zeros, and thus you should use - * g_unix_socket_address_get_path_len() to get the true length - * of this string. - * - * Returns: the path for @address - * Since: 2.22 - */ - - -/** - * g_unix_socket_address_get_path_len: - * @address: a #GInetSocketAddress - * - * Gets the length of @address's path. - * - * For details, see g_unix_socket_address_get_path(). - * - * Returns: the length of the path - * Since: 2.22 - */ - - -/** - * g_unix_socket_address_new: - * @path: the socket path - * - * Creates a new #GUnixSocketAddress for @path. - * - * To create abstract socket addresses, on systems that support that, - * use g_unix_socket_address_new_abstract(). - * - * Returns: a new #GUnixSocketAddress - * Since: 2.22 - */ - - -/** - * g_unix_socket_address_new_abstract: - * @path: (array length=path_len) (element-type gchar): the abstract name - * @path_len: the length of @path, or -1 - * - * Creates a new %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED - * #GUnixSocketAddress for @path. - * - * Returns: a new #GUnixSocketAddress - * Deprecated: Use g_unix_socket_address_new_with_type(). - */ - - -/** - * g_unix_socket_address_new_with_type: - * @path: (array length=path_len) (element-type gchar): the name - * @path_len: the length of @path, or -1 - * @type: a #GUnixSocketAddressType - * - * Creates a new #GUnixSocketAddress of type @type with name @path. - * - * If @type is %G_UNIX_SOCKET_ADDRESS_PATH, this is equivalent to - * calling g_unix_socket_address_new(). - * - * If @type is %G_UNIX_SOCKET_ADDRESS_ANONYMOUS, @path and @path_len will be - * ignored. - * - * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT, then @path_len - * bytes of @path will be copied to the socket's path, and only those - * bytes will be considered part of the name. (If @path_len is -1, - * then @path is assumed to be NUL-terminated.) For example, if @path - * was "test", then calling g_socket_address_get_native_size() on the - * returned socket would return 7 (2 bytes of overhead, 1 byte for the - * abstract-socket indicator byte, and 4 bytes for the name "test"). - * - * If @path_type is %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED, then - * @path_len bytes of @path will be copied to the socket's path, the - * rest of the path will be padded with 0 bytes, and the entire - * zero-padded buffer will be considered the name. (As above, if - * @path_len is -1, then @path is assumed to be NUL-terminated.) In - * this case, g_socket_address_get_native_size() will always return - * the full size of a `struct sockaddr_un`, although - * g_unix_socket_address_get_path_len() will still return just the - * length of @path. - * - * %G_UNIX_SOCKET_ADDRESS_ABSTRACT is preferred over - * %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED for new programs. Of course, - * when connecting to a server created by another process, you must - * use the appropriate type corresponding to how that process created - * its listening socket. - * - * Returns: a new #GUnixSocketAddress - * Since: 2.26 - */ - - -/** - * g_vfs_get_default: - * - * Gets the default #GVfs for the system. - * - * Returns: (not nullable) (transfer none): a #GVfs, which will be the local - * file system #GVfs if no other implementation is available. - */ - - -/** - * g_vfs_get_file_for_path: - * @vfs: a #GVfs. - * @path: a string containing a VFS path. - * - * Gets a #GFile for @path. - * - * Returns: (transfer full): a #GFile. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_vfs_get_file_for_uri: - * @vfs: a#GVfs. - * @uri: a string containing a URI - * - * Gets a #GFile for @uri. - * - * This operation never fails, but the returned object - * might not support any I/O operation if the URI - * is malformed or if the URI scheme is not supported. - * - * Returns: (transfer full): a #GFile. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_vfs_get_local: - * - * Gets the local #GVfs for the system. - * - * Returns: (transfer none): a #GVfs. - */ - - -/** - * g_vfs_get_supported_uri_schemes: - * @vfs: a #GVfs. - * - * Gets a list of URI schemes supported by @vfs. - * - * Returns: (transfer none): a %NULL-terminated array of strings. - * The returned array belongs to GIO and must - * not be freed or modified. - */ - - -/** - * g_vfs_is_active: - * @vfs: a #GVfs. - * - * Checks if the VFS is active. - * - * Returns: %TRUE if construction of the @vfs was successful - * and it is now active. - */ - - -/** - * g_vfs_parse_name: - * @vfs: a #GVfs. - * @parse_name: a string to be parsed by the VFS module. - * - * This operation never fails, but the returned object might - * not support any I/O operations if the @parse_name cannot - * be parsed by the #GVfs module. - * - * Returns: (transfer full): a #GFile for the given @parse_name. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_vfs_register_uri_scheme: - * @vfs: a #GVfs - * @scheme: an URI scheme, e.g. "http" - * @uri_func: (scope notified) (nullable): a #GVfsFileLookupFunc - * @uri_data: (nullable): custom data passed to be passed to @uri_func, or %NULL - * @uri_destroy: (nullable): function to be called when unregistering the - * URI scheme, or when @vfs is disposed, to free the resources used - * by the URI lookup function - * @parse_name_func: (scope notified) (nullable): a #GVfsFileLookupFunc - * @parse_name_data: (nullable): custom data passed to be passed to - * @parse_name_func, or %NULL - * @parse_name_destroy: (nullable): function to be called when unregistering the - * URI scheme, or when @vfs is disposed, to free the resources used - * by the parse name lookup function - * - * Registers @uri_func and @parse_name_func as the #GFile URI and parse name - * lookup functions for URIs with a scheme matching @scheme. - * Note that @scheme is registered only within the running application, as - * opposed to desktop-wide as it happens with GVfs backends. - * - * When a #GFile is requested with an URI containing @scheme (e.g. through - * g_file_new_for_uri()), @uri_func will be called to allow a custom - * constructor. The implementation of @uri_func should not be blocking, and - * must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme(). - * - * When g_file_parse_name() is called with a parse name obtained from such file, - * @parse_name_func will be called to allow the #GFile to be created again. In - * that case, it's responsibility of @parse_name_func to make sure the parse - * name matches what the custom #GFile implementation returned when - * g_file_get_parse_name() was previously called. The implementation of - * @parse_name_func should not be blocking, and must not call - * g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme(). - * - * It's an error to call this function twice with the same scheme. To unregister - * a custom URI scheme, use g_vfs_unregister_uri_scheme(). - * - * Returns: %TRUE if @scheme was successfully registered, or %FALSE if a handler - * for @scheme already exists. - * Since: 2.50 - */ - - -/** - * g_vfs_unregister_uri_scheme: - * @vfs: a #GVfs - * @scheme: an URI scheme, e.g. "http" - * - * Unregisters the URI handler for @scheme previously registered with - * g_vfs_register_uri_scheme(). - * - * Returns: %TRUE if @scheme was successfully unregistered, or %FALSE if a - * handler for @scheme does not exist. - * Since: 2.50 - */ - - -/** - * g_volume_can_eject: - * @volume: a #GVolume - * - * Checks if a volume can be ejected. - * - * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise - */ - - -/** - * g_volume_can_mount: - * @volume: a #GVolume - * - * Checks if a volume can be mounted. - * - * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise - */ - - -/** - * g_volume_eject: - * @volume: a #GVolume - * @flags: flags affecting the unmount if required for eject - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL - * @user_data: user data that gets passed to @callback - * - * Ejects a volume. This is an asynchronous operation, and is - * finished by calling g_volume_eject_finish() with the @volume - * and #GAsyncResult returned in the @callback. - * - * Deprecated: 2.22: Use g_volume_eject_with_operation() instead. - */ - - -/** - * g_volume_eject_finish: - * @volume: pointer to a #GVolume - * @result: a #GAsyncResult - * @error: a #GError location to store an error, or %NULL to ignore - * - * Finishes ejecting a volume. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. - * - * Returns: %TRUE, %FALSE if operation failed - * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead. - */ - - -/** - * g_volume_eject_with_operation: - * @volume: a #GVolume - * @flags: flags affecting the unmount if required for eject - * @mount_operation: (nullable): a #GMountOperation or %NULL to - * avoid user interaction - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL - * @user_data: user data passed to @callback - * - * Ejects a volume. This is an asynchronous operation, and is - * finished by calling g_volume_eject_with_operation_finish() with the @volume - * and #GAsyncResult data returned in the @callback. - * - * Since: 2.22 - */ - - -/** - * g_volume_eject_with_operation_finish: - * @volume: a #GVolume - * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL - * - * Finishes ejecting a volume. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. - * - * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise - * Since: 2.22 - */ - - -/** - * g_volume_enumerate_identifiers: - * @volume: a #GVolume - * - * Gets the kinds of [identifiers][volume-identifier] that @volume has. - * Use g_volume_get_identifier() to obtain the identifiers themselves. - * - * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array - * of strings containing kinds of identifiers. Use g_strfreev() to free. - */ - - -/** - * g_volume_get_activation_root: - * @volume: a #GVolume - * - * Gets the activation root for a #GVolume if it is known ahead of - * mount time. Returns %NULL otherwise. If not %NULL and if @volume - * is mounted, then the result of g_mount_get_root() on the - * #GMount object obtained from g_volume_get_mount() will always - * either be equal or a prefix of what this function returns. In - * other words, in code - * - * |[ - * GMount *mount; - * GFile *mount_root - * GFile *volume_activation_root; - * - * mount = g_volume_get_mount (volume); // mounted, so never NULL - * mount_root = g_mount_get_root (mount); - * volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL - * ]| - * then the expression - * |[ - * (g_file_has_prefix (volume_activation_root, mount_root) || - * g_file_equal (volume_activation_root, mount_root)) - * ]| - * will always be %TRUE. - * - * Activation roots are typically used in #GVolumeMonitor - * implementations to find the underlying mount to shadow, see - * g_mount_is_shadowed() for more details. - * - * Returns: (nullable) (transfer full): the activation root of @volume - * or %NULL. Use g_object_unref() to free. - * Since: 2.18 - */ - - -/** - * g_volume_get_drive: - * @volume: a #GVolume - * - * Gets the drive for the @volume. - * - * Returns: (transfer full) (nullable): a #GDrive or %NULL if @volume is not - * associated with a drive. The returned object should be unreffed - * with g_object_unref() when no longer needed. - */ - - -/** - * g_volume_get_icon: - * @volume: a #GVolume - * - * Gets the icon for @volume. - * - * Returns: (transfer full): a #GIcon. - * The returned object should be unreffed with g_object_unref() - * when no longer needed. - */ - - -/** - * g_volume_get_identifier: - * @volume: a #GVolume - * @kind: the kind of identifier to return - * - * Gets the identifier of the given kind for @volume. - * See the [introduction][volume-identifier] for more - * information about volume identifiers. - * - * Returns: (nullable) (transfer full): a newly allocated string containing the - * requested identifier, or %NULL if the #GVolume - * doesn't have this kind of identifier - */ - - -/** - * g_volume_get_mount: - * @volume: a #GVolume - * - * Gets the mount for the @volume. - * - * Returns: (transfer full) (nullable): a #GMount or %NULL if @volume isn't mounted. - * The returned object should be unreffed with g_object_unref() - * when no longer needed. - */ - - -/** - * g_volume_get_name: - * @volume: a #GVolume - * - * Gets the name of @volume. - * - * Returns: the name for the given @volume. The returned string should - * be freed with g_free() when no longer needed. - */ - - -/** - * g_volume_get_sort_key: - * @volume: a #GVolume - * - * Gets the sort key for @volume, if any. - * - * Returns: (nullable): Sorting key for @volume or %NULL if no such key is available - * Since: 2.32 - */ - - -/** - * g_volume_get_symbolic_icon: - * @volume: a #GVolume - * - * Gets the symbolic icon for @volume. - * - * Returns: (transfer full): a #GIcon. - * The returned object should be unreffed with g_object_unref() - * when no longer needed. - * Since: 2.34 - */ - - -/** - * g_volume_get_uuid: - * @volume: a #GVolume - * - * Gets the UUID for the @volume. The reference is typically based on - * the file system UUID for the volume in question and should be - * considered an opaque string. Returns %NULL if there is no UUID - * available. - * - * Returns: (nullable) (transfer full): the UUID for @volume or %NULL if no UUID - * can be computed. - * The returned string should be freed with g_free() - * when no longer needed. - */ - - -/** - * g_volume_monitor_adopt_orphan_mount: - * @mount: a #GMount object to find a parent for - * - * This function should be called by any #GVolumeMonitor - * implementation when a new #GMount object is created that is not - * associated with a #GVolume object. It must be called just before - * emitting the @mount_added signal. - * - * If the return value is not %NULL, the caller must associate the - * returned #GVolume object with the #GMount. This involves returning - * it in its g_mount_get_volume() implementation. The caller must - * also listen for the "removed" signal on the returned object - * and give up its reference when handling that signal - * - * Similarly, if implementing g_volume_monitor_adopt_orphan_mount(), - * the implementor must take a reference to @mount and return it in - * its g_volume_get_mount() implemented. Also, the implementor must - * listen for the "unmounted" signal on @mount and give up its - * reference upon handling that signal. - * - * There are two main use cases for this function. - * - * One is when implementing a user space file system driver that reads - * blocks of a block device that is already represented by the native - * volume monitor (for example a CD Audio file system driver). Such - * a driver will generate its own #GMount object that needs to be - * associated with the #GVolume object that represents the volume. - * - * The other is for implementing a #GVolumeMonitor whose sole purpose - * is to return #GVolume objects representing entries in the users - * "favorite servers" list or similar. - * - * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL - * if no wants to adopt the #GMount. - * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor - * implementations should instead create shadow mounts with the URI of - * the mount they intend to adopt. See the proxy volume monitor in - * gvfs for an example of this. Also see g_mount_is_shadowed(), - * g_mount_shadow() and g_mount_unshadow() functions. - */ - - -/** - * g_volume_monitor_get: - * - * Gets the volume monitor used by gio. - * - * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call - * g_object_unref() when done with it. - */ - - -/** - * g_volume_monitor_get_connected_drives: - * @volume_monitor: a #GVolumeMonitor. - * - * Gets a list of drives connected to the system. - * - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). - * - * Returns: (element-type GDrive) (transfer full): a #GList of connected #GDrive objects. - */ - - -/** - * g_volume_monitor_get_mount_for_uuid: - * @volume_monitor: a #GVolumeMonitor. - * @uuid: the UUID to look for - * - * Finds a #GMount object by its UUID (see g_mount_get_uuid()) - * - * Returns: (nullable) (transfer full): a #GMount or %NULL if no such mount is available. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_volume_monitor_get_mounts: - * @volume_monitor: a #GVolumeMonitor. - * - * Gets a list of the mounts on the system. - * - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). - * - * Returns: (element-type GMount) (transfer full): a #GList of #GMount objects. - */ - - -/** - * g_volume_monitor_get_volume_for_uuid: - * @volume_monitor: a #GVolumeMonitor. - * @uuid: the UUID to look for - * - * Finds a #GVolume object by its UUID (see g_volume_get_uuid()) - * - * Returns: (nullable) (transfer full): a #GVolume or %NULL if no such volume is available. - * Free the returned object with g_object_unref(). - */ - - -/** - * g_volume_monitor_get_volumes: - * @volume_monitor: a #GVolumeMonitor. - * - * Gets a list of the volumes on the system. - * - * The returned list should be freed with g_list_free(), after - * its elements have been unreffed with g_object_unref(). - * - * Returns: (element-type GVolume) (transfer full): a #GList of #GVolume objects. - */ - - -/** - * g_volume_mount: (virtual mount_fn) - * @volume: a #GVolume - * @flags: flags affecting the operation - * @mount_operation: (nullable): a #GMountOperation or %NULL to avoid user interaction - * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore - * @callback: (nullable): a #GAsyncReadyCallback, or %NULL - * @user_data: user data that gets passed to @callback - * - * Mounts a volume. This is an asynchronous operation, and is - * finished by calling g_volume_mount_finish() with the @volume - * and #GAsyncResult returned in the @callback. - */ - - -/** - * g_volume_mount_finish: - * @volume: a #GVolume - * @result: a #GAsyncResult - * @error: a #GError location to store an error, or %NULL to ignore - * - * Finishes mounting a volume. If any errors occurred during the operation, - * @error will be set to contain the errors and %FALSE will be returned. - * - * If the mount operation succeeded, g_volume_get_mount() on @volume - * is guaranteed to return the mount right after calling this - * function; there's no need to listen for the 'mount-added' signal on - * #GVolumeMonitor. - * - * Returns: %TRUE, %FALSE if operation failed - */ - - -/** - * g_volume_should_automount: - * @volume: a #GVolume - * - * Returns whether the volume should be automatically mounted. - * - * Returns: %TRUE if the volume should be automatically mounted - */ - - -/** - * g_win32_file_sync_stream_new: - * @handle: a Win32 HANDLE for a file. - * @owns_handle: %TRUE if newly-created stream owns the handle - * (and closes it when destroyed) - * @stgm_mode: a combination of [STGM constants](https://docs.microsoft.com/en-us/windows/win32/stg/stgm-constants) - * that specify the mode with which the stream - * is opened. - * @output_hresult: (out) (optional): a HRESULT from the internal COM calls. - * Will be `S_OK` on success. - * - * Creates an IStream object backed by a HANDLE. - * - * @stgm_mode should match the mode of the @handle, otherwise the stream might - * attempt to perform operations that the @handle does not allow. The implementation - * itself ignores these flags completely, they are only used to report - * the mode of the stream to third parties. - * - * The stream only does synchronous access and will never return `E_PENDING` on I/O. - * - * The returned stream object should be treated just like any other - * COM object, and released via `IUnknown_Release()`. - * its elements have been unreffed with g_object_unref(). - * - * Returns: (nullable) (transfer full): a new IStream object on success, %NULL on failure. - */ - - -/** - * g_win32_input_stream_get_close_handle: - * @stream: a #GWin32InputStream - * - * Returns whether the handle of @stream will be - * closed when the stream is closed. - * - * Returns: %TRUE if the handle is closed when done - * Since: 2.26 - */ - - -/** - * g_win32_input_stream_get_handle: - * @stream: a #GWin32InputStream - * - * Return the Windows file handle that the stream reads from. - * - * Returns: The file handle of @stream - * Since: 2.26 - */ - - -/** - * g_win32_input_stream_new: - * @handle: a Win32 file handle - * @close_handle: %TRUE to close the handle when done - * - * Creates a new #GWin32InputStream for the given @handle. - * - * If @close_handle is %TRUE, the handle will be closed - * when the stream is closed. - * - * Note that "handle" here means a Win32 HANDLE, not a "file descriptor" - * as used in the Windows C libraries. - * - * Returns: a new #GWin32InputStream - */ - - -/** - * g_win32_input_stream_set_close_handle: - * @stream: a #GWin32InputStream - * @close_handle: %TRUE to close the handle when done - * - * Sets whether the handle of @stream shall be closed - * when the stream is closed. - * - * Since: 2.26 - */ - - -/** - * g_win32_output_stream_get_close_handle: - * @stream: a #GWin32OutputStream - * - * Returns whether the handle of @stream will be closed when the - * stream is closed. - * - * Returns: %TRUE if the handle is closed when done - * Since: 2.26 - */ - - -/** - * g_win32_output_stream_get_handle: - * @stream: a #GWin32OutputStream - * - * Return the Windows handle that the stream writes to. - * - * Returns: The handle descriptor of @stream - * Since: 2.26 - */ - - -/** - * g_win32_output_stream_new: - * @handle: a Win32 file handle - * @close_handle: %TRUE to close the handle when done - * - * Creates a new #GWin32OutputStream for the given @handle. - * - * If @close_handle, is %TRUE, the handle will be closed when the - * output stream is destroyed. - * - * Returns: a new #GOutputStream - * Since: 2.26 - */ - - -/** - * g_win32_output_stream_set_close_handle: - * @stream: a #GWin32OutputStream - * @close_handle: %TRUE to close the handle when done - * - * Sets whether the handle of @stream shall be closed when the stream - * is closed. - * - * Since: 2.26 - */ - - -/** - * g_win32_registry_get_os_dirs: - * - * Returns a list of directories for DLL lookups. - * Can be used with g_win32_registry_key_get_value(). - * - * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of UTF-8 strings. - * Since: 2.66 - */ - - -/** - * g_win32_registry_get_os_dirs_w: - * - * Returns a list of directories for DLL lookups. - * Can be used with g_win32_registry_key_get_value_w(). - * - * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of UTF-16 strings. - * Since: 2.66 - */ - - -/** - * g_win32_registry_key_erase_change_indicator: - * @key: (in) (transfer none): a #GWin32RegistryKey - * - * Erases change indicator of the @key. - * - * Subsequent calls to g_win32_registry_key_has_changed() will return %FALSE - * until the key is put on watch again by calling - * g_win32_registry_key_watch() again. - * - * Since: 2.46 - */ - - -/** - * g_win32_registry_key_get_child: - * @key: (in) (transfer none): a parent #GWin32RegistryKey - * @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key - * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL - * - * Opens a @subkey of the @key. - * - * Returns: (nullable): a #GWin32RegistryKey or %NULL if can't be opened. Free - * with g_object_unref(). - */ - - -/** - * g_win32_registry_key_get_child_w: - * @key: (in) (transfer none): a parent #GWin32RegistryKey - * @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key - * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL - * - * Opens a @subkey of the @key. - * - * Returns: (nullable): a #GWin32RegistryKey or %NULL if can't be opened. Free - * with g_object_unref(). - */ - - -/** - * g_win32_registry_key_get_path: - * @key: (in) (transfer none): a #GWin32RegistryKey - * - * Get full path to the key - * - * Returns: (transfer none): a full path to the key (in UTF-8), - * or %NULL if it can't be converted to UTF-8. - * Since: 2.46 - */ - - -/** - * g_win32_registry_key_get_path_w: - * @key: (in) (transfer none): a #GWin32RegistryKey - * - * Get full path to the key - * - * Returns: (transfer none): a full path to the key (in UTF-16) - * Since: 2.46 - */ - - -/** - * g_win32_registry_key_get_value: - * @key: (in) (transfer none): a #GWin32RegistryKey - * @mui_dll_dirs: (in) (transfer none) (array zero-terminated=1) (optional): a %NULL-terminated - * array of directory names where the OS - * should look for a DLL indicated in a MUI string, if the - * DLL path in the string is not absolute - * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR - * to G_WIN32_REGISTRY_VALUE_STR. - * @value_name: (in) (transfer none): name of the value to get (in UTF-8). - * Empty string means the '(Default)' value. - * @value_type: (out) (optional): type of the value retrieved. - * @value_data: (out callee-allocates) (optional): contents of the value. - * @value_data_size: (out) (optional): size of the buffer pointed - * by @value_data. - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Get data from a value of a key. String data is guaranteed to be - * appropriately terminated and will be in UTF-8. - * - * When not %NULL, @mui_dll_dirs indicates that `RegLoadMUIStringW()` API - * should be used instead of the usual `RegQueryValueExW()`. This implies - * that the value being queried is of type `REG_SZ` or `REG_EXPAND_SZ` (if it is not, the function - * falls back to `RegQueryValueExW()`), and that this string must undergo special processing - * (see [`SHLoadIndirectString()` documentation](https://docs.microsoft.com/en-us/windows/win32/api/shlwapi/nf-shlwapi-shloadindirectstring) for an explanation on what - * kinds of strings are processed) to get the result. - * - * If no specific MUI DLL directories need to be used, pass - * the return value of g_win32_registry_get_os_dirs() as @mui_dll_dirs - * (as an bonus, the value from g_win32_registry_get_os_dirs() - * does not add any extra UTF8->UTF16 conversion overhead). - * - * @auto_expand works with @mui_dll_dirs, but only affects the processed - * string, making it somewhat useless. The unprocessed string is always expanded - * internally, if its type is `REG_EXPAND_SZ` - there is no need to enable - * @auto_expand for this to work. - * - * The API for this function changed in GLib 2.66 to add the @mui_dll_dirs argument. - * - * Returns: %TRUE on success, %FALSE on failure. - * Since: 2.66 - */ - - -/** - * g_win32_registry_key_get_value_w: - * @key: (in) (transfer none): a #GWin32RegistryKey - * @mui_dll_dirs: (in) (transfer none) (array zero-terminated=1) (optional): a %NULL-terminated - * array of directory names where the OS - * should look for a DLL indicated in a MUI string, if the - * DLL path in the string is not absolute - * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR - * to G_WIN32_REGISTRY_VALUE_STR. - * @value_name: (in) (transfer none): name of the value to get (in UTF-16). - * Empty string means the '(Default)' value. - * @value_type: (out) (optional): type of the value retrieved. - * @value_data: (out callee-allocates) (optional): contents of the value. - * @value_data_size: (out) (optional): size of the buffer pointed - * by @value_data. - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Get data from a value of a key. String data is guaranteed to be - * appropriately terminated and will be in UTF-16. - * - * When calling with value_data == NULL (to get data size without getting - * the data itself) remember that returned size corresponds to possibly - * unterminated string data (if value is some kind of string), because - * termination cannot be checked and fixed unless the data is retrieved - * too. - * - * When not %NULL, @mui_dll_dirs indicates that `RegLoadMUIStringW()` API - * should be used instead of the usual `RegQueryValueExW()`. This implies - * that the value being queried is of type `REG_SZ` or `REG_EXPAND_SZ` (if it is not, the function - * falls back to `RegQueryValueExW()`), and that this string must undergo special processing - * (see [`SHLoadIndirectString()` documentation](https://docs.microsoft.com/en-us/windows/win32/api/shlwapi/nf-shlwapi-shloadindirectstring) for an explanation on what - * kinds of strings are processed) to get the result. - * - * If no specific MUI DLL directories need to be used, pass - * the return value of g_win32_registry_get_os_dirs_w() as @mui_dll_dirs. - * - * @auto_expand works with @mui_dll_dirs, but only affects the processed - * string, making it somewhat useless. The unprocessed string is always expanded - * internally, if its type is `REG_EXPAND_SZ` - there is no need to enable - * @auto_expand for this to work. - * - * The API for this function changed in GLib 2.66 to add the @mui_dll_dirs argument. - * - * Returns: %TRUE on success, %FALSE on failure. - * Since: 2.66 - */ - - -/** - * g_win32_registry_key_has_changed: - * @key: (in) (transfer none): a #GWin32RegistryKey - * - * Check the @key's status indicator. - * - * Returns: %TRUE if the @key was put under watch at some point and has changed - * since then, %FALSE if it either wasn't changed or wasn't watched at all. - * Since: 2.46 - */ - - -/** - * g_win32_registry_key_new: - * @path: absolute full name of a key to open (in UTF-8) - * @error: (nullable): a pointer to a %NULL #GError, or %NULL - * - * Creates an object that represents a registry key specified by @path. - * @path must start with one of the following pre-defined names: - * - HKEY_CLASSES_ROOT - * - HKEY_CURRENT_CONFIG - * - HKEY_CURRENT_USER - * - HKEY_CURRENT_USER_LOCAL_SETTINGS - * - HKEY_LOCAL_MACHINE - * - HKEY_PERFORMANCE_DATA - * - HKEY_PERFORMANCE_NLSTEXT - * - HKEY_PERFORMANCE_TEXT - * - HKEY_USERS - * @path must not end with '\\'. - * - * Returns: (nullable) (transfer full): a #GWin32RegistryKey or %NULL if can't - * be opened. Free with g_object_unref(). - */ - - -/** - * g_win32_registry_key_new_w: - * @path: (in) (transfer none): absolute full name of a key to open (in UTF-16) - * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL - * - * Creates an object that represents a registry key specified by @path. - * @path must start with one of the following pre-defined names: - * - HKEY_CLASSES_ROOT - * - HKEY_CURRENT_CONFIG - * - HKEY_CURRENT_USER - * - HKEY_CURRENT_USER_LOCAL_SETTINGS - * - HKEY_LOCAL_MACHINE - * - HKEY_PERFORMANCE_DATA - * - HKEY_PERFORMANCE_NLSTEXT - * - HKEY_PERFORMANCE_TEXT - * - HKEY_USERS - * @path must not end with L'\\'. - * - * Returns: (nullable) (transfer full): a #GWin32RegistryKey or %NULL if can't - * be opened. Free with g_object_unref(). - */ - - -/** - * g_win32_registry_key_watch: - * @key: (in) (transfer none): a #GWin32RegistryKey - * @watch_children: (in): %TRUE also watch the children of the @key, %FALSE - * to watch the key only. - * @watch_flags: (in): specifies the types of changes to watch for. - * @callback: (in) (nullable): a function to invoke when a change occurs. - * @user_data: (in) (nullable): a pointer to pass to @callback on invocation. - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Puts @key under a watch. - * - * When the key changes, an APC will be queued in the current thread. The APC - * will run when the current thread enters alertable state (GLib main loop - * should do that; if you are not using it, see MSDN documentation for W32API - * calls that put thread into alertable state). When it runs, it will - * atomically switch an indicator in the @key. If a callback was specified, - * it is invoked at that point. Subsequent calls to - * g_win32_registry_key_has_changed() will return %TRUE, and the callback (if - * it was specified) will not be invoked anymore. - * Calling g_win32_registry_key_erase_change_indicator() will reset the indicator, - * and g_win32_registry_key_has_changed() will start returning %FALSE. - * To resume the watch, call g_win32_registry_key_watch_for_changes() again. - * - * Calling g_win32_registry_key_watch_for_changes() for a key that is already - * being watched is allowed and affects nothing. - * - * The fact that the key is being watched will be used internally to update - * key path (if it changes). - * - * Returns: %TRUE on success, %FALSE on failure. - * Since: 2.46 - */ - - -/** - * g_win32_registry_subkey_iter_assign: - * @iter: a #GWin32RegistrySubkeyIter - * @other: another #GWin32RegistrySubkeyIter - * - * Assigns the value of @other to @iter. This function - * is not useful in applications, because iterators can be assigned - * with `GWin32RegistrySubkeyIter i = j;`. The - * function is used by language bindings. - * - * Since: 2.46 - */ - - -/** - * g_win32_registry_subkey_iter_clear: - * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter - * - * Frees internal buffers of a #GWin32RegistrySubkeyIter. - * - * Since: 2.46 - */ - - -/** - * g_win32_registry_subkey_iter_copy: - * @iter: an iterator - * - * Creates a dynamically-allocated copy of an iterator. Dynamically-allocated - * state of the iterator is duplicated too. - * - * Returns: (transfer full): a copy of the @iter, - * free with g_win32_registry_subkey_iter_free () - * Since: 2.46 - */ - - -/** - * g_win32_registry_subkey_iter_free: - * @iter: a dynamically-allocated iterator - * - * Free an iterator allocated on the heap. For iterators that are allocated - * on the stack use g_win32_registry_subkey_iter_clear () instead. - * - * Since: 2.46 - */ - - -/** - * g_win32_registry_subkey_iter_get_name: - * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter - * @subkey_name: (out callee-allocates) (transfer none): Pointer to a location - * to store the name of a subkey (in UTF-8). Free with g_free(). - * @subkey_name_len: (out) (optional): Pointer to a location to store the - * length of @subkey_name, in gchars, excluding NUL-terminator. - * %NULL if length is not needed. - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Gets the name of the subkey at the @iter potision. - * - * Returns: %TRUE if the name was retrieved, %FALSE otherwise. - * Since: 2.46 - */ - - -/** - * g_win32_registry_subkey_iter_get_name_w: - * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter - * @subkey_name: (out callee-allocates) (transfer none): Pointer to a location - * to store the name of a subkey (in UTF-16). - * @subkey_name_len: (out) (optional) (transfer none): Pointer to a location - * to store the length of @subkey_name, in gunichar2s, excluding - * NUL-terminator. - * %NULL if length is not needed. - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Same as g_win32_registry_subkey_iter_get_next(), but outputs UTF-16-encoded - * data, without converting it to UTF-8 first. - * - * Returns: %TRUE if the name was retrieved, %FALSE otherwise. - * Since: 2.46 - */ - - -/** - * g_win32_registry_subkey_iter_init: - * @iter: (in) (transfer none): a pointer to a #GWin32RegistrySubkeyIter - * @key: (in) (transfer none): a #GWin32RegistryKey to iterate over - * @error: (inout) (optional) (nullable): a pointer to %NULL #GError, or %NULL - * - * Initialises (without allocating) a #GWin32RegistrySubkeyIter. @iter may be - * completely uninitialised prior to this call; its old value is - * ignored. - * - * The iterator remains valid for as long as @key exists. - * Clean up its internal buffers with a call to - * g_win32_registry_subkey_iter_clear() when done. - * - * Returns: %TRUE if iterator was initialized successfully, %FALSE on error. - * Since: 2.46 - */ - - -/** - * g_win32_registry_subkey_iter_n_subkeys: - * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter - * - * Queries the number of subkeys items in the key that we are - * iterating over. This is the total number of subkeys -- not the number - * of items remaining. - * - * This information is accurate at the point of iterator initialization, - * and may go out of sync with reality even while subkeys are enumerated. - * - * Returns: the number of subkeys in the key - * Since: 2.46 - */ - - -/** - * g_win32_registry_subkey_iter_next: - * @iter: (in) (transfer none): a #GWin32RegistrySubkeyIter - * @skip_errors: (in): %TRUE if iterator should silently ignore errors (such as - * the actual number of subkeys being less than expected) and - * proceed forward - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Moves iterator to the next subkey. - * Enumeration errors can be ignored if @skip_errors is %TRUE - * - * Here is an example for iterating with g_win32_registry_subkey_iter_next(): - * |[ - * // recursively iterate a key - * void - * iterate_key_recursive (GWin32RegistryKey *key) - * { - * GWin32RegistrySubkeyIter iter; - * gchar *name; - * GWin32RegistryKey *child; - * - * if (!g_win32_registry_subkey_iter_init (&iter, key, NULL)) - * return; - * - * while (g_win32_registry_subkey_iter_next (&iter, TRUE, NULL)) - * { - * if (!g_win32_registry_subkey_iter_get_name (&iter, &name, NULL, NULL)) - * continue; - * - * g_print ("subkey '%s'\n", name); - * child = g_win32_registry_key_get_child (key, name, NULL); - * - * if (child) - * iterate_key_recursive (child); - * } - * - * g_win32_registry_subkey_iter_clear (&iter); - * } - * ]| - * - * Returns: %TRUE if next subkey info was retrieved, %FALSE otherwise. - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_assign: - * @iter: a #GWin32RegistryValueIter - * @other: another #GWin32RegistryValueIter - * - * Assigns the value of @other to @iter. This function - * is not useful in applications, because iterators can be assigned - * with `GWin32RegistryValueIter i = j;`. The - * function is used by language bindings. - * - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_clear: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * - * Frees internal buffers of a #GWin32RegistryValueIter. - * - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_copy: - * @iter: an iterator - * - * Creates a dynamically-allocated copy of an iterator. Dynamically-allocated - * state of the iterator is duplicated too. - * - * Returns: (transfer full): a copy of the @iter, - * free with g_win32_registry_value_iter_free (). - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_free: - * @iter: a dynamically-allocated iterator - * - * Free an iterator allocated on the heap. For iterators that are allocated - * on the stack use g_win32_registry_value_iter_clear () instead. - * - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_get_data: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to - * G_WIN32_REGISTRY_VALUE_STR - * @value_data: (out callee-allocates) (optional) (transfer none): Pointer to a - * location to store the data of the value (in UTF-8, if it's a string) - * @value_data_size: (out) (optional): Pointer to a location to store the length - * of @value_data, in bytes (including any NUL-terminators, if it's a string). - * %NULL if length is not needed - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Stores the data of the value currently being iterated over in @value_data, - * and its length - in @value_data_len (if not %NULL). - * - * Returns: %TRUE if value data was retrieved, %FALSE otherwise. - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_get_data_w: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @auto_expand: (in): %TRUE to automatically expand G_WIN32_REGISTRY_VALUE_EXPAND_STR to - * G_WIN32_REGISTRY_VALUE_STR - * @value_data: (out callee-allocates) (optional) (transfer none): Pointer to a - * location to store the data of the value (in UTF-16, if it's a string) - * @value_data_size: (out) (optional): Pointer to a location to store the size - * of @value_data, in bytes (including any NUL-terminators, if it's a string). - * %NULL if length is not needed. - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Stores the data of the value currently being iterated over in @value_data, - * and its length - in @value_data_len (if not %NULL). - * - * Returns: %TRUE if value data was retrieved, %FALSE otherwise. - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_get_name: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @value_name: (out callee-allocates) (transfer none): Pointer to a location - * to store the name of a value (in UTF-8). - * @value_name_len: (out) (optional): Pointer to a location to store the length - * of @value_name, in gchars, excluding NUL-terminator. - * %NULL if length is not needed. - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Stores the name of the value currently being iterated over in @value_name, - * and its length - in @value_name_len (if not %NULL). - * - * Returns: %TRUE if value name was retrieved, %FALSE otherwise. - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_get_name_w: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @value_name: (out callee-allocates) (transfer none): Pointer to a location - * to store the name of a value (in UTF-16). - * @value_name_len: (out) (optional): Pointer to a location to store the length - * of @value_name, in gunichar2s, excluding NUL-terminator. - * %NULL if length is not needed. - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Stores the name of the value currently being iterated over in @value_name, - * and its length - in @value_name (if not %NULL). - * - * Returns: %TRUE if value name was retrieved, %FALSE otherwise. - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_get_value_type: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @value_type: (out): Pointer to a location to store the type of - * the value. - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Stores the type of the value currently being iterated over in @value_type. - * - * Returns: %TRUE if value type was retrieved, %FALSE otherwise. - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_init: - * @iter: (in) (transfer none): a pointer to a #GWin32RegistryValueIter - * @key: (in) (transfer none): a #GWin32RegistryKey to iterate over - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Initialises (without allocating) a #GWin32RegistryValueIter. @iter may be - * completely uninitialised prior to this call; its old value is - * ignored. - * - * The iterator remains valid for as long as @key exists. - * Clean up its internal buffers with a call to - * g_win32_registry_value_iter_clear() when done. - * - * Returns: %TRUE if iterator was initialized successfully, %FALSE on error. - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_n_values: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * - * Queries the number of values items in the key that we are - * iterating over. This is the total number of values -- not the number - * of items remaining. - * - * This information is accurate at the point of iterator initialization, - * and may go out of sync with reality even while values are enumerated. - * - * Returns: the number of values in the key - * Since: 2.46 - */ - - -/** - * g_win32_registry_value_iter_next: - * @iter: (in) (transfer none): a #GWin32RegistryValueIter - * @skip_errors: (in): %TRUE if iterator should silently ignore errors (such as - * the actual number of values being less than expected) and - * proceed forward - * @error: (nullable): a pointer to %NULL #GError, or %NULL - * - * Advances iterator to the next value in the key. If no more values remain then - * FALSE is returned. - * Enumeration errors can be ignored if @skip_errors is %TRUE - * - * Here is an example for iterating with g_win32_registry_value_iter_next(): - * |[ - * // iterate values of a key - * void - * iterate_values_recursive (GWin32RegistryKey *key) - * { - * GWin32RegistryValueIter iter; - * gchar *name; - * GWin32RegistryValueType val_type; - * gchar *val_data; - * - * if (!g_win32_registry_value_iter_init (&iter, key, NULL)) - * return; - * - * while (g_win32_registry_value_iter_next (&iter, TRUE, NULL)) - * { - * if ((!g_win32_registry_value_iter_get_value_type (&iter, &value)) || - * ((val_type != G_WIN32_REGISTRY_VALUE_STR) && - * (val_type != G_WIN32_REGISTRY_VALUE_EXPAND_STR))) - * continue; - * - * if (g_win32_registry_value_iter_get_value (&iter, TRUE, &name, NULL, - * &val_data, NULL, NULL)) - * g_print ("value '%s' = '%s'\n", name, val_data); - * } - * - * g_win32_registry_value_iter_clear (&iter); - * } - * ]| - * - * Returns: %TRUE if next value info was retrieved, %FALSE otherwise. - * Since: 2.46 - */ - - -/** - * g_zlib_compressor_get_file_info: - * @compressor: a #GZlibCompressor - * - * Returns the #GZlibCompressor:file-info property. - * - * Returns: (nullable) (transfer none): a #GFileInfo, or %NULL - * Since: 2.26 - */ - - -/** - * g_zlib_compressor_new: - * @format: The format to use for the compressed data - * @level: compression level (0-9), -1 for default - * - * Creates a new #GZlibCompressor. - * - * Returns: a new #GZlibCompressor - * Since: 2.24 - */ - - -/** - * g_zlib_compressor_set_file_info: - * @compressor: a #GZlibCompressor - * @file_info: (nullable): a #GFileInfo - * - * Sets @file_info in @compressor. If non-%NULL, and @compressor's - * #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, - * it will be used to set the file name and modification time in - * the GZIP header of the compressed data. - * - * Note: it is an error to call this function while a compression is in - * progress; it may only be called immediately after creation of @compressor, - * or after resetting it with g_converter_reset(). - * - * Since: 2.26 - */ - - -/** - * g_zlib_decompressor_get_file_info: - * @decompressor: a #GZlibDecompressor - * - * Retrieves the #GFileInfo constructed from the GZIP header data - * of compressed data processed by @compressor, or %NULL if @decompressor's - * #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP, - * or the header data was not fully processed yet, or it not present in the - * data stream at all. - * - * Returns: (nullable) (transfer none): a #GFileInfo, or %NULL - * Since: 2.26 - */ - - -/** - * g_zlib_decompressor_new: - * @format: The format to use for the compressed data - * - * Creates a new #GZlibDecompressor. - * - * Returns: a new #GZlibDecompressor - * Since: 2.24 - */ - - -/** - * get_viewable_logical_drives: - * - * Returns the list of logical and viewable drives as defined by - * GetLogicalDrives() and the registry keys - * Software\Microsoft\Windows\CurrentVersion\Policies\Explorer under - * HKLM or HKCU. If neither key exists the result of - * GetLogicalDrives() is returned. - * - * Returns: bitmask with same meaning as returned by GetLogicalDrives() - */ - - - -/************************************************************/ -/* THIS FILE IS GENERATED DO NOT EDIT */ -/************************************************************/ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c deleted file mode 100644 index 2d2810ea..00000000 --- a/gir/glib-2.0.c +++ /dev/null @@ -1,42618 +0,0 @@ -/************************************************************/ -/* THIS FILE IS GENERATED DO NOT EDIT */ -/************************************************************/ - -/** - * ABS: - * @a: a numeric value - * - * Calculates the absolute value of @a. - * The absolute value is simply the number with any negative sign taken away. - * - * For example, - * - ABS(-10) is 10. - * - ABS(10) is also 10. - * - * Returns: the absolute value of @a. - */ - - -/** - * CLAMP: - * @x: the value to clamp - * @low: the minimum value allowed - * @high: the maximum value allowed - * - * Ensures that @x is between the limits set by @low and @high. If @low is - * greater than @high the result is undefined. - * - * For example, - * - CLAMP(5, 10, 15) is 10. - * - CLAMP(15, 5, 10) is 10. - * - CLAMP(20, 15, 25) is 20. - * - * Returns: the value of @x clamped to the range between @low and @high - */ - - -/** - * C_: - * @Context: a message context, must be a string literal - * @String: a message id, must be a string literal - * - * Uses gettext to get the translation for @String. @Context is - * used as a context. This is mainly useful for short strings which - * may need different translations, depending on the context in which - * they are used. - * |[ - * label1 = C_("Navigation", "Back"); - * label2 = C_("Body part", "Back"); - * ]| - * - * If you are using the C_() macro, you need to make sure that you pass - * `--keyword=C_:1c,2` to xgettext when extracting messages. - * Note that this only works with GNU gettext >= 0.15. - * - * Returns: the translated message - * Since: 2.16 - */ - - -/** - * FALSE: - * - * Defines the %FALSE value for the #gboolean type. - */ - - -/** - * GArray: - * @data: a pointer to the element data. The data may be moved as - * elements are added to the #GArray. - * @len: the number of elements in the #GArray not including the - * possible terminating zero element. - * - * Contains the public fields of a GArray. - */ - - -/** - * GAsyncQueue: - * - * An opaque data structure which represents an asynchronous queue. - * - * It should only be accessed through the `g_async_queue_*` functions. - */ - - -/** - * GByteArray: - * @data: a pointer to the element data. The data may be moved as - * elements are added to the #GByteArray - * @len: the number of elements in the #GByteArray - * - * Contains the public fields of a GByteArray. - */ - - -/** - * GBytes: - * - * A simple refcounted data type representing an immutable sequence of zero or - * more bytes from an unspecified origin. - * - * The purpose of a #GBytes is to keep the memory region that it holds - * alive for as long as anyone holds a reference to the bytes. When - * the last reference count is dropped, the memory is released. Multiple - * unrelated callers can use byte data in the #GBytes without coordinating - * their activities, resting assured that the byte data will not change or - * move while they hold a reference. - * - * A #GBytes can come from many different origins that may have - * different procedures for freeing the memory region. Examples are - * memory from g_malloc(), from memory slices, from a #GMappedFile or - * memory from other allocators. - * - * #GBytes work well as keys in #GHashTable. Use g_bytes_equal() and - * g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full(). - * #GBytes can also be used as keys in a #GTree by passing the g_bytes_compare() - * function to g_tree_new(). - * - * The data pointed to by this bytes must not be modified. For a mutable - * array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a - * mutable array for a #GBytes sequence. To create an immutable #GBytes from - * a mutable #GByteArray, use the g_byte_array_free_to_bytes() function. - * - * Since: 2.32 - */ - - -/** - * GCompareDataFunc: - * @a: a value - * @b: a value to compare with - * @user_data: user data - * - * Specifies the type of a comparison function used to compare two - * values. The function should return a negative integer if the first - * value comes before the second, 0 if they are equal, or a positive - * integer if the first value comes after the second. - * - * Returns: negative value if @a < @b; zero if @a = @b; positive - * value if @a > @b - */ - - -/** - * GCompareFunc: - * @a: a value - * @b: a value to compare with - * - * Specifies the type of a comparison function used to compare two - * values. The function should return a negative integer if the first - * value comes before the second, 0 if they are equal, or a positive - * integer if the first value comes after the second. - * - * Returns: negative value if @a < @b; zero if @a = @b; positive - * value if @a > @b - */ - - -/** - * GCond: - * - * The #GCond struct is an opaque data structure that represents a - * condition. Threads can block on a #GCond if they find a certain - * condition to be false. If other threads change the state of this - * condition they signal the #GCond, and that causes the waiting - * threads to be woken up. - * - * Consider the following example of a shared variable. One or more - * threads can wait for data to be published to the variable and when - * another thread publishes the data, it can signal one of the waiting - * threads to wake up to collect the data. - * - * Here is an example for using GCond to block a thread until a condition - * is satisfied: - * |[ - * gpointer current_data = NULL; - * GMutex data_mutex; - * GCond data_cond; - * - * void - * push_data (gpointer data) - * { - * g_mutex_lock (&data_mutex); - * current_data = data; - * g_cond_signal (&data_cond); - * g_mutex_unlock (&data_mutex); - * } - * - * gpointer - * pop_data (void) - * { - * gpointer data; - * - * g_mutex_lock (&data_mutex); - * while (!current_data) - * g_cond_wait (&data_cond, &data_mutex); - * data = current_data; - * current_data = NULL; - * g_mutex_unlock (&data_mutex); - * - * return data; - * } - * ]| - * Whenever a thread calls pop_data() now, it will wait until - * current_data is non-%NULL, i.e. until some other thread - * has called push_data(). - * - * The example shows that use of a condition variable must always be - * paired with a mutex. Without the use of a mutex, there would be a - * race between the check of @current_data by the while loop in - * pop_data() and waiting. Specifically, another thread could set - * @current_data after the check, and signal the cond (with nobody - * waiting on it) before the first thread goes to sleep. #GCond is - * specifically useful for its ability to release the mutex and go - * to sleep atomically. - * - * It is also important to use the g_cond_wait() and g_cond_wait_until() - * functions only inside a loop which checks for the condition to be - * true. See g_cond_wait() for an explanation of why the condition may - * not be true even after it returns. - * - * If a #GCond is allocated in static storage then it can be used - * without initialisation. Otherwise, you should call g_cond_init() - * on it and g_cond_clear() when done. - * - * A #GCond should only be accessed via the g_cond_ functions. - */ - - -/** - * GData: - * - * An opaque data structure that represents a keyed data list. - * - * See also: [Keyed data lists][glib-Keyed-Data-Lists]. - */ - - -/** - * GDataForeachFunc: - * @key_id: the #GQuark id to identifying the data element. - * @data: the data element. - * @user_data: (closure): user data passed to g_dataset_foreach(). - * - * Specifies the type of function passed to g_dataset_foreach(). It is - * called with each #GQuark id and associated data element, together - * with the @user_data parameter supplied to g_dataset_foreach(). - */ - - -/** - * GDate: - * @julian_days: the Julian representation of the date - * @julian: this bit is set if @julian_days is valid - * @dmy: this is set if @day, @month and @year are valid - * @day: the day of the day-month-year representation of the date, - * as a number between 1 and 31 - * @month: the day of the day-month-year representation of the date, - * as a number between 1 and 12 - * @year: the day of the day-month-year representation of the date - * - * Represents a day between January 1, Year 1 and a few thousand years in - * the future. None of its members should be accessed directly. - * - * If the `GDate` is obtained from g_date_new(), it will be safe - * to mutate but invalid and thus not safe for calendrical computations. - * - * If it's declared on the stack, it will contain garbage so must be - * initialized with g_date_clear(). g_date_clear() makes the date invalid - * but safe. An invalid date doesn't represent a day, it's "empty." A date - * becomes valid after you set it to a Julian day or you set a day, month, - * and year. - */ - - -/** - * GDateDMY: - * @G_DATE_DAY: a day - * @G_DATE_MONTH: a month - * @G_DATE_YEAR: a year - * - * This enumeration isn't used in the API, but may be useful if you need - * to mark a number as a day, month, or year. - */ - - -/** - * GDateDay: - * - * Integer representing a day of the month; between 1 and 31. - * - * The %G_DATE_BAD_DAY value represents an invalid day of the month. - */ - - -/** - * GDateMonth: - * @G_DATE_BAD_MONTH: invalid value - * @G_DATE_JANUARY: January - * @G_DATE_FEBRUARY: February - * @G_DATE_MARCH: March - * @G_DATE_APRIL: April - * @G_DATE_MAY: May - * @G_DATE_JUNE: June - * @G_DATE_JULY: July - * @G_DATE_AUGUST: August - * @G_DATE_SEPTEMBER: September - * @G_DATE_OCTOBER: October - * @G_DATE_NOVEMBER: November - * @G_DATE_DECEMBER: December - * - * Enumeration representing a month; values are %G_DATE_JANUARY, - * %G_DATE_FEBRUARY, etc. %G_DATE_BAD_MONTH is the invalid value. - */ - - -/** - * GDateWeekday: - * @G_DATE_BAD_WEEKDAY: invalid value - * @G_DATE_MONDAY: Monday - * @G_DATE_TUESDAY: Tuesday - * @G_DATE_WEDNESDAY: Wednesday - * @G_DATE_THURSDAY: Thursday - * @G_DATE_FRIDAY: Friday - * @G_DATE_SATURDAY: Saturday - * @G_DATE_SUNDAY: Sunday - * - * Enumeration representing a day of the week; #G_DATE_MONDAY, - * #G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday. - */ - - -/** - * GDateYear: - * - * Integer type representing a year. - * - * The %G_DATE_BAD_YEAR value is the invalid value. The year - * must be 1 or higher; negative ([BCE](https://en.wikipedia.org/wiki/Common_Era)) - * years are not allowed. - * - * The year is represented with four digits. - */ - - -/** - * GDestroyNotify: - * @data: the data element. - * - * Specifies the type of function which is called when a data element - * is destroyed. It is passed the pointer to the data element and - * should free any memory and resources allocated for it. - */ - - -/** - * GDir: - * - * An opaque structure representing an opened directory. - */ - - -/** - * GDoubleIEEE754: - * @v_double: the double value - * - * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, - * mantissa and exponent of IEEE floats and doubles. These unions are defined - * as appropriate for a given platform. IEEE floats and doubles are supported - * (used for storage) by at least Intel, PPC and Sparc. - */ - - -/** - * GDuplicateFunc: - * @data: the data to duplicate - * @user_data: (closure): user data that was specified in - * g_datalist_id_dup_data() - * - * The type of functions that are used to 'duplicate' an object. - * What this means depends on the context, it could just be - * incrementing the reference count, if @data is a ref-counted - * object. - * - * Returns: a duplicate of data - */ - - -/** - * GEqualFunc: - * @a: a value - * @b: a value to compare with - * - * Specifies the type of a function used to test two values for - * equality. The function should return %TRUE if both values are equal - * and %FALSE otherwise. - * - * Returns: %TRUE if @a = @b; %FALSE otherwise - */ - - -/** - * GErrorType: - * @G_ERR_UNKNOWN: unknown error - * @G_ERR_UNEXP_EOF: unexpected end of file - * @G_ERR_UNEXP_EOF_IN_STRING: unterminated string constant - * @G_ERR_UNEXP_EOF_IN_COMMENT: unterminated comment - * @G_ERR_NON_DIGIT_IN_CONST: non-digit character in a number - * @G_ERR_DIGIT_RADIX: digit beyond radix in a number - * @G_ERR_FLOAT_RADIX: non-decimal floating point number - * @G_ERR_FLOAT_MALFORMED: malformed floating point number - * - * The possible errors, used in the @v_error field - * of #GTokenValue, when the token is a %G_TOKEN_ERROR. - */ - - -/** - * GFileError: - * @G_FILE_ERROR_EXIST: Operation not permitted; only the owner of - * the file (or other resource) or processes with special privileges - * can perform the operation. - * @G_FILE_ERROR_ISDIR: File is a directory; you cannot open a directory - * for writing, or create or remove hard links to it. - * @G_FILE_ERROR_ACCES: Permission denied; the file permissions do not - * allow the attempted operation. - * @G_FILE_ERROR_NAMETOOLONG: Filename too long. - * @G_FILE_ERROR_NOENT: No such file or directory. This is a "file - * doesn't exist" error for ordinary files that are referenced in - * contexts where they are expected to already exist. - * @G_FILE_ERROR_NOTDIR: A file that isn't a directory was specified when - * a directory is required. - * @G_FILE_ERROR_NXIO: No such device or address. The system tried to - * use the device represented by a file you specified, and it - * couldn't find the device. This can mean that the device file was - * installed incorrectly, or that the physical device is missing or - * not correctly attached to the computer. - * @G_FILE_ERROR_NODEV: The underlying file system of the specified file - * does not support memory mapping. - * @G_FILE_ERROR_ROFS: The directory containing the new link can't be - * modified because it's on a read-only file system. - * @G_FILE_ERROR_TXTBSY: Text file busy. - * @G_FILE_ERROR_FAULT: You passed in a pointer to bad memory. - * (GLib won't reliably return this, don't pass in pointers to bad - * memory.) - * @G_FILE_ERROR_LOOP: Too many levels of symbolic links were encountered - * in looking up a file name. This often indicates a cycle of symbolic - * links. - * @G_FILE_ERROR_NOSPC: No space left on device; write operation on a - * file failed because the disk is full. - * @G_FILE_ERROR_NOMEM: No memory available. The system cannot allocate - * more virtual memory because its capacity is full. - * @G_FILE_ERROR_MFILE: The current process has too many files open and - * can't open any more. Duplicate descriptors do count toward this - * limit. - * @G_FILE_ERROR_NFILE: There are too many distinct file openings in the - * entire system. - * @G_FILE_ERROR_BADF: Bad file descriptor; for example, I/O on a - * descriptor that has been closed or reading from a descriptor open - * only for writing (or vice versa). - * @G_FILE_ERROR_INVAL: Invalid argument. This is used to indicate - * various kinds of problems with passing the wrong argument to a - * library function. - * @G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the - * other end of a pipe. Every library function that returns this - * error code also generates a 'SIGPIPE' signal; this signal - * terminates the program if not handled or blocked. Thus, your - * program will never actually see this code unless it has handled - * or blocked 'SIGPIPE'. - * @G_FILE_ERROR_AGAIN: Resource temporarily unavailable; the call might - * work if you try again later. - * @G_FILE_ERROR_INTR: Interrupted function call; an asynchronous signal - * occurred and prevented completion of the call. When this - * happens, you should try the call again. - * @G_FILE_ERROR_IO: Input/output error; usually used for physical read - * or write errors. i.e. the disk or other physical device hardware - * is returning errors. - * @G_FILE_ERROR_PERM: Operation not permitted; only the owner of the - * file (or other resource) or processes with special privileges can - * perform the operation. - * @G_FILE_ERROR_NOSYS: Function not implemented; this indicates that - * the system is missing some functionality. - * @G_FILE_ERROR_FAILED: Does not correspond to a UNIX error code; this - * is the standard "failed for unspecified reason" error code present - * in all #GError error code enumerations. Returned if no specific - * code applies. - * - * Values corresponding to @errno codes returned from file operations - * on UNIX. Unlike @errno codes, GFileError values are available on - * all systems, even Windows. The exact meaning of each code depends - * on what sort of file operation you were performing; the UNIX - * documentation gives more details. The following error code descriptions - * come from the GNU C Library manual, and are under the copyright - * of that manual. - * - * It's not very portable to make detailed assumptions about exactly - * which errors will be returned from a given operation. Some errors - * don't occur on some systems, etc., sometimes there are subtle - * differences in when a system will report a given error, etc. - */ - - -/** - * GFileTest: - * @G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file - * (not a directory). Note that this test will also return %TRUE - * if the tested file is a symlink to a regular file. - * @G_FILE_TEST_IS_SYMLINK: %TRUE if the file is a symlink. - * @G_FILE_TEST_IS_DIR: %TRUE if the file is a directory. - * @G_FILE_TEST_IS_EXECUTABLE: %TRUE if the file is executable. - * @G_FILE_TEST_EXISTS: %TRUE if the file exists. It may or may not - * be a regular file. - * - * A test to perform on a file using g_file_test(). - */ - - -/** - * GFloatIEEE754: - * @v_float: the double value - * - * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, - * mantissa and exponent of IEEE floats and doubles. These unions are defined - * as appropriate for a given platform. IEEE floats and doubles are supported - * (used for storage) by at least Intel, PPC and Sparc. - */ - - -/** - * GFormatSizeFlags: - * @G_FORMAT_SIZE_DEFAULT: behave the same as g_format_size() - * @G_FORMAT_SIZE_LONG_FORMAT: include the exact number of bytes as part - * of the returned string. For example, "45.6 kB (45,612 bytes)". - * @G_FORMAT_SIZE_IEC_UNITS: use IEC (base 1024) units with "KiB"-style - * suffixes. IEC units should only be used for reporting things with - * a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. - * Network and storage sizes should be reported in the normal SI units. - * @G_FORMAT_SIZE_BITS: set the size as a quantity in bits, rather than - * bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’. - * - * Flags to modify the format of the string returned by g_format_size_full(). - */ - - -/** - * GFunc: - * @data: the element's data - * @user_data: user data passed to g_list_foreach() or g_slist_foreach() - * - * Specifies the type of functions passed to g_list_foreach() and - * g_slist_foreach(). - */ - - -/** - * GHFunc: - * @key: a key - * @value: the value corresponding to the key - * @user_data: user data passed to g_hash_table_foreach() - * - * Specifies the type of the function passed to g_hash_table_foreach(). - * It is called with each key/value pair, together with the @user_data - * parameter which is passed to g_hash_table_foreach(). - */ - - -/** - * GHRFunc: - * @key: a key - * @value: the value associated with the key - * @user_data: user data passed to g_hash_table_remove() - * - * Specifies the type of the function passed to - * g_hash_table_foreach_remove(). It is called with each key/value - * pair, together with the @user_data parameter passed to - * g_hash_table_foreach_remove(). It should return %TRUE if the - * key/value pair should be removed from the #GHashTable. - * - * Returns: %TRUE if the key/value pair should be removed from the - * #GHashTable - */ - - -/** - * GHashFunc: - * @key: a key - * - * Specifies the type of the hash function which is passed to - * g_hash_table_new() when a #GHashTable is created. - * - * The function is passed a key and should return a #guint hash value. - * The functions g_direct_hash(), g_int_hash() and g_str_hash() provide - * hash functions which can be used when the key is a #gpointer, #gint*, - * and #gchar* respectively. - * - * g_direct_hash() is also the appropriate hash function for keys - * of the form `GINT_TO_POINTER (n)` (or similar macros). - * - * A good hash functions should produce - * hash values that are evenly distributed over a fairly large range. - * The modulus is taken with the hash table size (a prime number) to - * find the 'bucket' to place each key into. The function should also - * be very fast, since it is called for each key lookup. - * - * Note that the hash functions provided by GLib have these qualities, - * but are not particularly robust against manufactured keys that - * cause hash collisions. Therefore, you should consider choosing - * a more secure hash function when using a GHashTable with keys - * that originate in untrusted data (such as HTTP requests). - * Using g_str_hash() in that situation might make your application - * vulnerable to - * [Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/). - * - * The key to choosing a good hash is unpredictability. Even - * cryptographic hashes are very easy to find collisions for when the - * remainder is taken modulo a somewhat predictable prime number. There - * must be an element of randomness that an attacker is unable to guess. - * - * Returns: the hash value corresponding to the key - */ - - -/** - * GHashTable: - * - * The #GHashTable struct is an opaque data structure to represent a - * [Hash Table][glib-Hash-Tables]. It should only be accessed via the - * following functions. - */ - - -/** - * GHashTableIter: - * - * A GHashTableIter structure represents an iterator that can be used - * to iterate over the elements of a #GHashTable. GHashTableIter - * structures are typically allocated on the stack and then initialized - * with g_hash_table_iter_init(). - * - * The iteration order of a #GHashTableIter over the keys/values in a hash - * table is not defined. - */ - - -/** - * GHook: - * @data: data which is passed to func when this hook is invoked - * @next: pointer to the next hook in the list - * @prev: pointer to the previous hook in the list - * @ref_count: the reference count of this hook - * @hook_id: the id of this hook, which is unique within its list - * @flags: flags which are set for this hook. See #GHookFlagMask for - * predefined flags - * @func: the function to call when this hook is invoked. The possible - * signatures for this function are #GHookFunc and #GHookCheckFunc - * @destroy: the default @finalize_hook function of a #GHookList calls - * this member of the hook that is being finalized - * - * The #GHook struct represents a single hook function in a #GHookList. - */ - - -/** - * GHookCheckFunc: - * @data: the data field of the #GHook is passed to the hook function here - * - * Defines the type of a hook function that can be invoked - * by g_hook_list_invoke_check(). - * - * Returns: %FALSE if the #GHook should be destroyed - */ - - -/** - * GHookCheckMarshaller: - * @hook: a #GHook - * @marshal_data: user data - * - * Defines the type of function used by g_hook_list_marshal_check(). - * - * Returns: %FALSE if @hook should be destroyed - */ - - -/** - * GHookCompareFunc: - * @new_hook: the #GHook being inserted - * @sibling: the #GHook to compare with @new_hook - * - * Defines the type of function used to compare #GHook elements in - * g_hook_insert_sorted(). - * - * Returns: a value <= 0 if @new_hook should be before @sibling - */ - - -/** - * GHookFinalizeFunc: - * @hook_list: a #GHookList - * @hook: the hook in @hook_list that gets finalized - * - * Defines the type of function to be called when a hook in a - * list of hooks gets finalized. - */ - - -/** - * GHookFindFunc: - * @hook: a #GHook - * @data: user data passed to g_hook_find_func() - * - * Defines the type of the function passed to g_hook_find(). - * - * Returns: %TRUE if the required #GHook has been found - */ - - -/** - * GHookFlagMask: - * @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed - * @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run - * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for - * hook flags; see %G_HOOK_FLAG_USER_SHIFT - * - * Flags used internally in the #GHook implementation. - */ - - -/** - * GHookFunc: - * @data: the data field of the #GHook is passed to the hook function here - * - * Defines the type of a hook function that can be invoked - * by g_hook_list_invoke(). - */ - - -/** - * GHookList: - * @seq_id: the next free #GHook id - * @hook_size: the size of the #GHookList elements, in bytes - * @is_setup: 1 if the #GHookList has been initialized - * @hooks: the first #GHook element in the list - * @dummy3: unused - * @finalize_hook: the function to call to finalize a #GHook element. - * The default behaviour is to call the hooks @destroy function - * @dummy: unused - * - * The #GHookList struct represents a list of hook functions. - */ - - -/** - * GHookMarshaller: - * @hook: a #GHook - * @marshal_data: user data - * - * Defines the type of function used by g_hook_list_marshal(). - */ - - -/** - * GINT16_FROM_BE: - * @val: a #gint16 value in big-endian byte order - * - * Converts a #gint16 value from big-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GINT16_FROM_LE: - * @val: a #gint16 value in little-endian byte order - * - * Converts a #gint16 value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GINT16_TO_BE: - * @val: a #gint16 value in host byte order - * - * Converts a #gint16 value from host byte order to big-endian. - * - * Returns: @val converted to big-endian - */ - - -/** - * GINT16_TO_LE: - * @val: a #gint16 value in host byte order - * - * Converts a #gint16 value from host byte order to little-endian. - * - * Returns: @val converted to little-endian - */ - - -/** - * GINT32_FROM_BE: - * @val: a #gint32 value in big-endian byte order - * - * Converts a #gint32 value from big-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GINT32_FROM_LE: - * @val: a #gint32 value in little-endian byte order - * - * Converts a #gint32 value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GINT32_TO_BE: - * @val: a #gint32 value in host byte order - * - * Converts a #gint32 value from host byte order to big-endian. - * - * Returns: @val converted to big-endian - */ - - -/** - * GINT32_TO_LE: - * @val: a #gint32 value in host byte order - * - * Converts a #gint32 value from host byte order to little-endian. - * - * Returns: @val converted to little-endian - */ - - -/** - * GINT64_FROM_BE: - * @val: a #gint64 value in big-endian byte order - * - * Converts a #gint64 value from big-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GINT64_FROM_LE: - * @val: a #gint64 value in little-endian byte order - * - * Converts a #gint64 value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GINT64_TO_BE: - * @val: a #gint64 value in host byte order - * - * Converts a #gint64 value from host byte order to big-endian. - * - * Returns: @val converted to big-endian - */ - - -/** - * GINT64_TO_LE: - * @val: a #gint64 value in host byte order - * - * Converts a #gint64 value from host byte order to little-endian. - * - * Returns: @val converted to little-endian - */ - - -/** - * GINT_FROM_BE: - * @val: a #gint value in big-endian byte order - * - * Converts a #gint value from big-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GINT_FROM_LE: - * @val: a #gint value in little-endian byte order - * - * Converts a #gint value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GINT_TO_BE: - * @val: a #gint value in host byte order - * - * Converts a #gint value from host byte order to big-endian. - * - * Returns: @val converted to big-endian byte order - */ - - -/** - * GINT_TO_LE: - * @val: a #gint value in host byte order - * - * Converts a #gint value from host byte order to little-endian. - * - * Returns: @val converted to little-endian byte order - */ - - -/** - * GINT_TO_POINTER: - * @i: integer to stuff into a pointer - * - * Stuffs an integer into a pointer type. - * - * Remember, you may not store pointers in integers. This is not portable - * in any way, shape or form. These macros only allow storing integers in - * pointers, and only preserve 32 bits of the integer; values outside the - * range of a 32-bit integer will be mangled. - */ - - -/** - * GIOChannel: - * - * A data structure representing an IO Channel. The fields should be - * considered private and should only be accessed with the following - * functions. - */ - - -/** - * GIOChannelError: - * @G_IO_CHANNEL_ERROR_FBIG: File too large. - * @G_IO_CHANNEL_ERROR_INVAL: Invalid argument. - * @G_IO_CHANNEL_ERROR_IO: IO error. - * @G_IO_CHANNEL_ERROR_ISDIR: File is a directory. - * @G_IO_CHANNEL_ERROR_NOSPC: No space left on device. - * @G_IO_CHANNEL_ERROR_NXIO: No such device or address. - * @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype. - * @G_IO_CHANNEL_ERROR_PIPE: Broken pipe. - * @G_IO_CHANNEL_ERROR_FAILED: Some other error. - * - * Error codes returned by #GIOChannel operations. - */ - - -/** - * GIOCondition: - * @G_IO_IN: There is data to read. - * @G_IO_OUT: Data can be written (without blocking). - * @G_IO_PRI: There is urgent data to read. - * @G_IO_ERR: Error condition. - * @G_IO_HUP: Hung up (the connection has been broken, usually for - * pipes and sockets). - * @G_IO_NVAL: Invalid request. The file descriptor is not open. - * - * A bitwise combination representing a condition to watch for on an - * event source. - */ - - -/** - * GIOError: - * @G_IO_ERROR_NONE: no error - * @G_IO_ERROR_AGAIN: an EAGAIN error occurred - * @G_IO_ERROR_INVAL: an EINVAL error occurred - * @G_IO_ERROR_UNKNOWN: another error occurred - * - * #GIOError is only used by the deprecated functions - * g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek(). - */ - - -/** - * GIOFlags: - * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND - * (see the documentation of the UNIX open() syscall) - * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to - * %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() - * syscall) - * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. - * This flag cannot be changed. - * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable. - * This flag cannot be changed. - * @G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE - * that existed before the spelling was fixed in GLib 2.30. It is kept - * here for compatibility reasons. Deprecated since 2.30 - * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, - * i.e. that g_io_channel_seek_position() can be used on it. - * This flag cannot be changed. - * @G_IO_FLAG_MASK: the mask that specifies all the valid flags. - * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from - * g_io_channel_get_flags() - * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify - * with g_io_channel_set_flags() - * - * Specifies properties of a #GIOChannel. Some of the flags can only be - * read with g_io_channel_get_flags(), but not changed with - * g_io_channel_set_flags(). - */ - - -/** - * GIOFunc: - * @source: the #GIOChannel event source - * @condition: the condition which has been satisfied - * @data: user data set in g_io_add_watch() or g_io_add_watch_full() - * - * Specifies the type of function passed to g_io_add_watch() or - * g_io_add_watch_full(), which is called when the requested condition - * on a #GIOChannel is satisfied. - * - * Returns: the function should return %FALSE if the event source - * should be removed - */ - - -/** - * GIOFuncs: - * @io_read: reads raw bytes from the channel. This is called from - * various functions such as g_io_channel_read_chars() to - * read raw bytes from the channel. Encoding and buffering - * issues are dealt with at a higher level. - * @io_write: writes raw bytes to the channel. This is called from - * various functions such as g_io_channel_write_chars() to - * write raw bytes to the channel. Encoding and buffering - * issues are dealt with at a higher level. - * @io_seek: (optional): seeks the channel. This is called from - * g_io_channel_seek() on channels that support it. - * @io_close: closes the channel. This is called from - * g_io_channel_close() after flushing the buffers. - * @io_create_watch: creates a watch on the channel. This call - * corresponds directly to g_io_create_watch(). - * @io_free: called from g_io_channel_unref() when the channel needs to - * be freed. This function must free the memory associated - * with the channel, including freeing the #GIOChannel - * structure itself. The channel buffers have been flushed - * and possibly @io_close has been called by the time this - * function is called. - * @io_set_flags: sets the #GIOFlags on the channel. This is called - * from g_io_channel_set_flags() with all flags except - * for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked - * out. - * @io_get_flags: gets the #GIOFlags for the channel. This function - * need only return the %G_IO_FLAG_APPEND and - * %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags() - * automatically adds the others as appropriate. - * - * A table of functions used to handle different types of #GIOChannel - * in a generic way. - */ - - -/** - * GIOStatus: - * @G_IO_STATUS_ERROR: An error occurred. - * @G_IO_STATUS_NORMAL: Success. - * @G_IO_STATUS_EOF: End of file. - * @G_IO_STATUS_AGAIN: Resource temporarily unavailable. - * - * Statuses returned by most of the #GIOFuncs functions. - */ - - -/** - * GKeyFile: - * - * The GKeyFile struct contains only private data - * and should not be accessed directly. - */ - - -/** - * GKeyFileError: - * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in - * an unknown encoding - * @G_KEY_FILE_ERROR_PARSE: document was ill-formed - * @G_KEY_FILE_ERROR_NOT_FOUND: the file was not found - * @G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found - * @G_KEY_FILE_ERROR_GROUP_NOT_FOUND: a requested group was not found - * @G_KEY_FILE_ERROR_INVALID_VALUE: a value could not be parsed - * - * Error codes returned by key file parsing. - */ - - -/** - * GKeyFileFlags: - * @G_KEY_FILE_NONE: No flags, default behaviour - * @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the - * (possibly modified) contents of the key file back to a file; - * otherwise all comments will be lost when the key file is - * written back. - * @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the - * (possibly modified) contents of the key file back to a file; - * otherwise only the translations for the current language will be - * written back. - * - * Flags which influence the parsing. - */ - - -/** - * GLIB_CHECK_VERSION: - * @major: the major version to check for - * @minor: the minor version to check for - * @micro: the micro version to check for - * - * Checks the version of the GLib library that is being compiled - * against. See glib_check_version() for a runtime check. - * - * Returns: %TRUE if the version of the GLib header files - * is the same as or newer than the passed-in version. - */ - - -/** - * GLIB_DISABLE_DEPRECATION_WARNINGS: - * - * A macro that should be defined before including the glib.h header. - * If it is defined, no compiler warnings will be produced for uses - * of deprecated GLib APIs. - */ - - -/** - * GLIB_MAJOR_VERSION: - * - * The major version number of the GLib library. - * - * Like #glib_major_version, but from the headers used at - * application compile time, rather than from the library - * linked against at application run time. - */ - - -/** - * GLIB_MICRO_VERSION: - * - * The micro version number of the GLib library. - * - * Like #gtk_micro_version, but from the headers used at - * application compile time, rather than from the library - * linked against at application run time. - */ - - -/** - * GLIB_MINOR_VERSION: - * - * The minor version number of the GLib library. - * - * Like #gtk_minor_version, but from the headers used at - * application compile time, rather than from the library - * linked against at application run time. - */ - - -/** - * GLONG_FROM_BE: - * @val: a #glong value in big-endian byte order - * - * Converts a #glong value from big-endian to the host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GLONG_FROM_LE: - * @val: a #glong value in little-endian byte order - * - * Converts a #glong value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GLONG_TO_BE: - * @val: a #glong value in host byte order - * - * Converts a #glong value from host byte order to big-endian. - * - * Returns: @val converted to big-endian byte order - */ - - -/** - * GLONG_TO_LE: - * @val: a #glong value in host byte order - * - * Converts a #glong value from host byte order to little-endian. - * - * Returns: @val converted to little-endian - */ - - -/** - * GList: - * @data: holds the element's data, which can be a pointer to any kind - * of data, or any integer value using the - * [Type Conversion Macros][glib-Type-Conversion-Macros] - * @next: contains the link to the next element in the list - * @prev: contains the link to the previous element in the list - * - * The #GList struct is used for each element in a doubly-linked list. - */ - - -/** - * GLogFunc: - * @log_domain: the log domain of the message - * @log_level: the log level of the message (including the - * fatal and recursion flags) - * @message: the message to process - * @user_data: user data, set in g_log_set_handler() - * - * Specifies the prototype of log handler functions. - * - * The default log handler, g_log_default_handler(), automatically appends a - * new-line character to @message when printing it. It is advised that any - * custom log handler functions behave similarly, so that logging calls in user - * code do not need modifying to add a new-line character to the message if the - * log handler is changed. - * - * This is not used if structured logging is enabled; see - * [Using Structured Logging][using-structured-logging]. - */ - - -/** - * GLogLevelFlags: - * @G_LOG_FLAG_RECURSION: internal flag - * @G_LOG_FLAG_FATAL: internal flag - * @G_LOG_LEVEL_ERROR: log level for errors, see g_error(). - * This level is also used for messages produced by g_assert(). - * @G_LOG_LEVEL_CRITICAL: log level for critical warning messages, see - * g_critical(). - * This level is also used for messages produced by g_return_if_fail() - * and g_return_val_if_fail(). - * @G_LOG_LEVEL_WARNING: log level for warnings, see g_warning() - * @G_LOG_LEVEL_MESSAGE: log level for messages, see g_message() - * @G_LOG_LEVEL_INFO: log level for informational messages, see g_info() - * @G_LOG_LEVEL_DEBUG: log level for debug messages, see g_debug() - * @G_LOG_LEVEL_MASK: a mask including all log levels - * - * Flags specifying the level of log messages. - * - * It is possible to change how GLib treats messages of the various - * levels using g_log_set_handler() and g_log_set_fatal_mask(). - */ - - -/** - * GMappedFile: - * - * The #GMappedFile represents a file mapping created with - * g_mapped_file_new(). It has only private members and should - * not be accessed directly. - */ - - -/** - * GMarkupCollectType: - * @G_MARKUP_COLLECT_INVALID: used to terminate the list of attributes - * to collect - * @G_MARKUP_COLLECT_STRING: collect the string pointer directly from - * the attribute_values[] array. Expects a parameter of type (const - * char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the - * attribute isn't present then the pointer will be set to %NULL - * @G_MARKUP_COLLECT_STRDUP: as with %G_MARKUP_COLLECT_STRING, but - * expects a parameter of type (char **) and g_strdup()s the - * returned pointer. The pointer must be freed with g_free() - * @G_MARKUP_COLLECT_BOOLEAN: expects a parameter of type (gboolean *) - * and parses the attribute value as a boolean. Sets %FALSE if the - * attribute isn't present. Valid boolean values consist of - * (case-insensitive) "false", "f", "no", "n", "0" and "true", "t", - * "yes", "y", "1" - * @G_MARKUP_COLLECT_TRISTATE: as with %G_MARKUP_COLLECT_BOOLEAN, but - * in the case of a missing attribute a value is set that compares - * equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is - * implied - * @G_MARKUP_COLLECT_OPTIONAL: can be bitwise ORed with the other fields. - * If present, allows the attribute not to appear. A default value - * is set depending on what value type is used - * - * A mixed enumerated type and flags field. You must specify one type - * (string, strdup, boolean, tristate). Additionally, you may optionally - * bitwise OR the type with the flag %G_MARKUP_COLLECT_OPTIONAL. - * - * It is likely that this enum will be extended in the future to - * support other types. - */ - - -/** - * GMutex: - * - * The #GMutex struct is an opaque data structure to represent a mutex - * (mutual exclusion). It can be used to protect data against shared - * access. - * - * Take for example the following function: - * |[ - * int - * give_me_next_number (void) - * { - * static int current_number = 0; - * - * // now do a very complicated calculation to calculate the new - * // number, this might for example be a random number generator - * current_number = calc_next_number (current_number); - * - * return current_number; - * } - * ]| - * It is easy to see that this won't work in a multi-threaded - * application. There current_number must be protected against shared - * access. A #GMutex can be used as a solution to this problem: - * |[ - * int - * give_me_next_number (void) - * { - * static GMutex mutex; - * static int current_number = 0; - * int ret_val; - * - * g_mutex_lock (&mutex); - * ret_val = current_number = calc_next_number (current_number); - * g_mutex_unlock (&mutex); - * - * return ret_val; - * } - * ]| - * Notice that the #GMutex is not initialised to any particular value. - * Its placement in static storage ensures that it will be initialised - * to all-zeros, which is appropriate. - * - * If a #GMutex is placed in other contexts (eg: embedded in a struct) - * then it must be explicitly initialised using g_mutex_init(). - * - * A #GMutex should only be accessed via g_mutex_ functions. - */ - - -/** - * GNode: - * @data: contains the actual data of the node. - * @next: points to the node's next sibling (a sibling is another - * #GNode with the same parent). - * @prev: points to the node's previous sibling. - * @parent: points to the parent of the #GNode, or is %NULL if the - * #GNode is the root of the tree. - * @children: points to the first child of the #GNode. The other - * children are accessed by using the @next pointer of each - * child. - * - * The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees]. - */ - - -/** - * GNodeForeachFunc: - * @node: a #GNode. - * @data: user data passed to g_node_children_foreach(). - * - * Specifies the type of function passed to g_node_children_foreach(). - * The function is called with each child node, together with the user - * data passed to g_node_children_foreach(). - */ - - -/** - * GNodeTraverseFunc: - * @node: a #GNode. - * @data: user data passed to g_node_traverse(). - * - * Specifies the type of function passed to g_node_traverse(). The - * function is called with each of the nodes visited, together with the - * user data passed to g_node_traverse(). If the function returns - * %TRUE, then the traversal is stopped. - * - * Returns: %TRUE to stop the traversal. - */ - - -/** - * GOnce: - * @status: the status of the #GOnce - * @retval: the value returned by the call to the function, if @status - * is %G_ONCE_STATUS_READY - * - * A #GOnce struct controls a one-time initialization function. Any - * one-time initialization function must have its own unique #GOnce - * struct. - * - * Since: 2.4 - */ - - -/** - * GOnceStatus: - * @G_ONCE_STATUS_NOTCALLED: the function has not been called yet. - * @G_ONCE_STATUS_PROGRESS: the function call is currently in progress. - * @G_ONCE_STATUS_READY: the function has been called. - * - * The possible statuses of a one-time initialization function - * controlled by a #GOnce struct. - * - * Since: 2.4 - */ - - -/** - * GPOINTER_TO_INT: - * @p: pointer containing an integer - * - * Extracts an integer from a pointer. The integer must have - * been stored in the pointer with GINT_TO_POINTER(). - * - * Remember, you may not store pointers in integers. This is not portable - * in any way, shape or form. These macros only allow storing integers in - * pointers, and only preserve 32 bits of the integer; values outside the - * range of a 32-bit integer will be mangled. - */ - - -/** - * GPOINTER_TO_SIZE: - * @p: pointer to extract a #gsize from - * - * Extracts a #gsize from a pointer. The #gsize must have - * been stored in the pointer with GSIZE_TO_POINTER(). - */ - - -/** - * GPOINTER_TO_UINT: - * @p: pointer to extract an unsigned integer from - * - * Extracts an unsigned integer from a pointer. The integer must have - * been stored in the pointer with GUINT_TO_POINTER(). - */ - - -/** - * GPatternSpec: - * - * A GPatternSpec struct is the 'compiled' form of a pattern. This - * structure is opaque and its fields cannot be accessed directly. - */ - - -/** - * GPrivate: - * - * The #GPrivate struct is an opaque data structure to represent a - * thread-local data key. It is approximately equivalent to the - * pthread_setspecific()/pthread_getspecific() APIs on POSIX and to - * TlsSetValue()/TlsGetValue() on Windows. - * - * If you don't already know why you might want this functionality, - * then you probably don't need it. - * - * #GPrivate is a very limited resource (as far as 128 per program, - * shared between all libraries). It is also not possible to destroy a - * #GPrivate after it has been used. As such, it is only ever acceptable - * to use #GPrivate in static scope, and even then sparingly so. - * - * See G_PRIVATE_INIT() for a couple of examples. - * - * The #GPrivate structure should be considered opaque. It should only - * be accessed via the g_private_ functions. - */ - - -/** - * GPtrArray: - * @pdata: points to the array of pointers, which may be moved when the - * array grows - * @len: number of pointers in the array - * - * Contains the public fields of a pointer array. - */ - - -/** - * GQuark: - * - * A GQuark is a non-zero integer which uniquely identifies a - * particular string. A GQuark value of zero is associated to %NULL. - */ - - -/** - * GRWLock: - * - * The GRWLock struct is an opaque data structure to represent a - * reader-writer lock. It is similar to a #GMutex in that it allows - * multiple threads to coordinate access to a shared resource. - * - * The difference to a mutex is that a reader-writer lock discriminates - * between read-only ('reader') and full ('writer') access. While only - * one thread at a time is allowed write access (by holding the 'writer' - * lock via g_rw_lock_writer_lock()), multiple threads can gain - * simultaneous read-only access (by holding the 'reader' lock via - * g_rw_lock_reader_lock()). - * - * It is unspecified whether readers or writers have priority in acquiring the - * lock when a reader already holds the lock and a writer is queued to acquire - * it. - * - * Here is an example for an array with access functions: - * |[ - * GRWLock lock; - * GPtrArray *array; - * - * gpointer - * my_array_get (guint index) - * { - * gpointer retval = NULL; - * - * if (!array) - * return NULL; - * - * g_rw_lock_reader_lock (&lock); - * if (index < array->len) - * retval = g_ptr_array_index (array, index); - * g_rw_lock_reader_unlock (&lock); - * - * return retval; - * } - * - * void - * my_array_set (guint index, gpointer data) - * { - * g_rw_lock_writer_lock (&lock); - * - * if (!array) - * array = g_ptr_array_new (); - * - * if (index >= array->len) - * g_ptr_array_set_size (array, index+1); - * g_ptr_array_index (array, index) = data; - * - * g_rw_lock_writer_unlock (&lock); - * } - * ]| - * This example shows an array which can be accessed by many readers - * (the my_array_get() function) simultaneously, whereas the writers - * (the my_array_set() function) will only be allowed one at a time - * and only if no readers currently access the array. This is because - * of the potentially dangerous resizing of the array. Using these - * functions is fully multi-thread safe now. - * - * If a #GRWLock is allocated in static storage then it can be used - * without initialisation. Otherwise, you should call - * g_rw_lock_init() on it and g_rw_lock_clear() when done. - * - * A GRWLock should only be accessed with the g_rw_lock_ functions. - * - * Since: 2.32 - */ - - -/** - * GRand: - * - * The GRand struct is an opaque data structure. It should only be - * accessed through the g_rand_* functions. - */ - - -/** - * GRecMutex: - * - * The GRecMutex struct is an opaque data structure to represent a - * recursive mutex. It is similar to a #GMutex with the difference - * that it is possible to lock a GRecMutex multiple times in the same - * thread without deadlock. When doing so, care has to be taken to - * unlock the recursive mutex as often as it has been locked. - * - * If a #GRecMutex is allocated in static storage then it can be used - * without initialisation. Otherwise, you should call - * g_rec_mutex_init() on it and g_rec_mutex_clear() when done. - * - * A GRecMutex should only be accessed with the - * g_rec_mutex_ functions. - * - * Since: 2.32 - */ - - -/** - * GSIZE_FROM_BE: - * @val: a #gsize value in big-endian byte order - * - * Converts a #gsize value from big-endian to the host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GSIZE_FROM_LE: - * @val: a #gsize value in little-endian byte order - * - * Converts a #gsize value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GSIZE_TO_BE: - * @val: a #gsize value in host byte order - * - * Converts a #gsize value from host byte order to big-endian. - * - * Returns: @val converted to big-endian byte order - */ - - -/** - * GSIZE_TO_LE: - * @val: a #gsize value in host byte order - * - * Converts a #gsize value from host byte order to little-endian. - * - * Returns: @val converted to little-endian - */ - - -/** - * GSIZE_TO_POINTER: - * @s: #gsize to stuff into the pointer - * - * Stuffs a #gsize into a pointer type. - */ - - -/** - * GSList: - * @data: holds the element's data, which can be a pointer to any kind - * of data, or any integer value using the - * [Type Conversion Macros][glib-Type-Conversion-Macros] - * @next: contains the link to the next element in the list. - * - * The #GSList struct is used for each element in the singly-linked - * list. - */ - - -/** - * GSSIZE_FROM_BE: - * @val: a #gssize value in big-endian byte order - * - * Converts a #gssize value from big-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GSSIZE_FROM_LE: - * @val: a #gssize value in little-endian byte order - * - * Converts a #gssize value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GSSIZE_TO_BE: - * @val: a #gssize value in host byte order - * - * Converts a #gssize value from host byte order to big-endian. - * - * Returns: @val converted to big-endian - */ - - -/** - * GSSIZE_TO_LE: - * @val: a #gssize value in host byte order - * - * Converts a #gssize value from host byte order to little-endian. - * - * Returns: @val converted to little-endian - */ - - -/** - * GScanner: - * @user_data: unused - * @max_parse_errors: unused - * @parse_errors: g_scanner_error() increments this field - * @input_name: name of input stream, featured by the default message handler - * @qdata: quarked data - * @config: link into the scanner configuration - * @token: token parsed by the last g_scanner_get_next_token() - * @value: value of the last token from g_scanner_get_next_token() - * @line: line number of the last token from g_scanner_get_next_token() - * @position: char number of the last token from g_scanner_get_next_token() - * @next_token: token parsed by the last g_scanner_peek_next_token() - * @next_value: value of the last token from g_scanner_peek_next_token() - * @next_line: line number of the last token from g_scanner_peek_next_token() - * @next_position: char number of the last token from g_scanner_peek_next_token() - * @msg_handler: handler function for _warn and _error - * - * The data structure representing a lexical scanner. - * - * You should set @input_name after creating the scanner, since - * it is used by the default message handler when displaying - * warnings and errors. If you are scanning a file, the filename - * would be a good choice. - * - * The @user_data and @max_parse_errors fields are not used. - * If you need to associate extra data with the scanner you - * can place them here. - * - * If you want to use your own message handler you can set the - * @msg_handler field. The type of the message handler function - * is declared by #GScannerMsgFunc. - */ - - -/** - * GScannerConfig: - * @cset_skip_characters: specifies which characters should be skipped - * by the scanner (the default is the whitespace characters: space, - * tab, carriage-return and line-feed). - * @cset_identifier_first: specifies the characters which can start - * identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). - * @cset_identifier_nth: specifies the characters which can be used - * in identifiers, after the first character (the default is - * #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, - * #G_CSET_LATINC). - * @cpair_comment_single: specifies the characters at the start and - * end of single-line comments. The default is "#\n" which means - * that single-line comments start with a '#' and continue until - * a '\n' (end of line). - * @case_sensitive: specifies if symbols are case sensitive (the - * default is %FALSE). - * @skip_comment_multi: specifies if multi-line comments are skipped - * and not returned as tokens (the default is %TRUE). - * @skip_comment_single: specifies if single-line comments are skipped - * and not returned as tokens (the default is %TRUE). - * @scan_comment_multi: specifies if multi-line comments are recognized - * (the default is %TRUE). - * @scan_identifier: specifies if identifiers are recognized (the - * default is %TRUE). - * @scan_identifier_1char: specifies if single-character - * identifiers are recognized (the default is %FALSE). - * @scan_identifier_NULL: specifies if %NULL is reported as - * %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE). - * @scan_symbols: specifies if symbols are recognized (the default - * is %TRUE). - * @scan_binary: specifies if binary numbers are recognized (the - * default is %FALSE). - * @scan_octal: specifies if octal numbers are recognized (the - * default is %TRUE). - * @scan_float: specifies if floating point numbers are recognized - * (the default is %TRUE). - * @scan_hex: specifies if hexadecimal numbers are recognized (the - * default is %TRUE). - * @scan_hex_dollar: specifies if '$' is recognized as a prefix for - * hexadecimal numbers (the default is %FALSE). - * @scan_string_sq: specifies if strings can be enclosed in single - * quotes (the default is %TRUE). - * @scan_string_dq: specifies if strings can be enclosed in double - * quotes (the default is %TRUE). - * @numbers_2_int: specifies if binary, octal and hexadecimal numbers - * are reported as #G_TOKEN_INT (the default is %TRUE). - * @int_2_float: specifies if all numbers are reported as %G_TOKEN_FLOAT - * (the default is %FALSE). - * @identifier_2_string: specifies if identifiers are reported as strings - * (the default is %FALSE). - * @char_2_token: specifies if characters are reported by setting - * `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE). - * @symbol_2_token: specifies if symbols are reported by setting - * `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE). - * @scope_0_fallback: specifies if a symbol is searched for in the - * default scope in addition to the current scope (the default is %FALSE). - * @store_int64: use value.v_int64 rather than v_int - * - * Specifies the #GScanner parser configuration. Most settings can - * be changed during the parsing phase and will affect the lexical - * parsing of the next unpeeked token. - */ - - -/** - * GScannerMsgFunc: - * @scanner: a #GScanner - * @message: the message - * @error: %TRUE if the message signals an error, - * %FALSE if it signals a warning. - * - * Specifies the type of the message handler function. - */ - - -/** - * GSeekType: - * @G_SEEK_CUR: the current position in the file. - * @G_SEEK_SET: the start of the file. - * @G_SEEK_END: the end of the file. - * - * An enumeration specifying the base position for a - * g_io_channel_seek_position() operation. - */ - - -/** - * GSequence: - * - * The #GSequence struct is an opaque data type representing a - * [sequence][glib-Sequences] data type. - */ - - -/** - * GSequenceIter: - * - * The #GSequenceIter struct is an opaque data type representing an - * iterator pointing into a #GSequence. - */ - - -/** - * GSequenceIterCompareFunc: - * @a: a #GSequenceIter - * @b: a #GSequenceIter - * @data: user data - * - * A #GSequenceIterCompareFunc is a function used to compare iterators. - * It must return zero if the iterators compare equal, a negative value - * if @a comes before @b, and a positive value if @b comes before @a. - * - * Returns: zero if the iterators are equal, a negative value if @a - * comes before @b, and a positive value if @b comes before @a. - */ - - -/** - * GShellError: - * @G_SHELL_ERROR_BAD_QUOTING: Mismatched or otherwise mangled quoting. - * @G_SHELL_ERROR_EMPTY_STRING: String to be parsed was empty. - * @G_SHELL_ERROR_FAILED: Some other error. - * - * Error codes returned by shell functions. - */ - - -/** - * GStatBuf: - * - * A type corresponding to the appropriate struct type for the stat() - * system call, depending on the platform and/or compiler being used. - * - * See g_stat() for more information. - */ - - -/** - * GString: - * @str: points to the character data. It may move as text is added. - * The @str field is null-terminated and so - * can be used as an ordinary C string. - * @len: contains the length of the string, not including the - * terminating nul byte. - * @allocated_len: the number of bytes that can be stored in the - * string before it needs to be reallocated. May be larger than @len. - * - * The GString struct contains the public fields of a GString. - */ - - -/** - * GStringChunk: - * - * An opaque data structure representing String Chunks. - * It should only be accessed by using the following functions. - */ - - -/** - * GStrv: - * - * A typedef alias for gchar**. This is mostly useful when used together with - * g_auto(). - */ - - -/** - * GTestCase: - * - * An opaque structure representing a test case. - */ - - -/** - * GTestDataFunc: - * @user_data: the data provided when registering the test - * - * The type used for test case functions that take an extra pointer - * argument. - * - * Since: 2.28 - */ - - -/** - * GTestFileType: - * @G_TEST_DIST: a file that was included in the distribution tarball - * @G_TEST_BUILT: a file that was built on the compiling machine - * - * The type of file to return the filename for, when used with - * g_test_build_filename(). - * - * These two options correspond rather directly to the 'dist' and - * 'built' terminology that automake uses and are explicitly used to - * distinguish between the 'srcdir' and 'builddir' being separate. All - * files in your project should either be dist (in the - * `EXTRA_DIST` or `dist_schema_DATA` - * sense, in which case they will always be in the srcdir) or built (in - * the `BUILT_SOURCES` sense, in which case they will - * always be in the builddir). - * - * Note: as a general rule of automake, files that are generated only as - * part of the build-from-git process (but then are distributed with the - * tarball) always go in srcdir (even if doing a srcdir != builddir - * build from git) and are considered as distributed files. - * - * Since: 2.38 - */ - - -/** - * GTestFixtureFunc: - * @fixture: (not nullable): the test fixture - * @user_data: the data provided when registering the test - * - * The type used for functions that operate on test fixtures. This is - * used for the fixture setup and teardown functions as well as for the - * testcases themselves. - * - * @user_data is a pointer to the data that was given when registering - * the test case. - * - * @fixture will be a pointer to the area of memory allocated by the - * test framework, of the size requested. If the requested size was - * zero then @fixture will be equal to @user_data. - * - * Since: 2.28 - */ - - -/** - * GTestFunc: - * - * The type used for test case functions. - * - * Since: 2.28 - */ - - -/** - * GTestSubprocessFlags: - * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child - * process will inherit the parent's stdin. Otherwise, the child's - * stdin is redirected to `/dev/null`. - * @G_TEST_SUBPROCESS_INHERIT_STDOUT: If this flag is given, the child - * process will inherit the parent's stdout. Otherwise, the child's - * stdout will not be visible, but it will be captured to allow - * later tests with g_test_trap_assert_stdout(). - * @G_TEST_SUBPROCESS_INHERIT_STDERR: If this flag is given, the child - * process will inherit the parent's stderr. Otherwise, the child's - * stderr will not be visible, but it will be captured to allow - * later tests with g_test_trap_assert_stderr(). - * - * Flags to pass to g_test_trap_subprocess() to control input and output. - * - * Note that in contrast with g_test_trap_fork(), the default is to - * not show stdout and stderr. - */ - - -/** - * GTestSuite: - * - * An opaque structure representing a test suite. - */ - - -/** - * GThread: - * - * The #GThread struct represents a running thread. This struct - * is returned by g_thread_new() or g_thread_try_new(). You can - * obtain the #GThread struct representing the current thread by - * calling g_thread_self(). - * - * GThread is refcounted, see g_thread_ref() and g_thread_unref(). - * The thread represented by it holds a reference while it is running, - * and g_thread_join() consumes the reference that it is given, so - * it is normally not necessary to manage GThread references - * explicitly. - * - * The structure is opaque -- none of its fields may be directly - * accessed. - */ - - -/** - * GThreadError: - * @G_THREAD_ERROR_AGAIN: a thread couldn't be created due to resource - * shortage. Try again later. - * - * Possible errors of thread related functions. - */ - - -/** - * GThreadFunc: - * @data: data passed to the thread - * - * Specifies the type of the @func functions passed to g_thread_new() - * or g_thread_try_new(). - * - * Returns: the return value of the thread - */ - - -/** - * GThreadPool: - * @func: the function to execute in the threads of this pool - * @user_data: the user data for the threads of this pool - * @exclusive: are all threads exclusive to this pool - * - * The #GThreadPool struct represents a thread pool. It has three - * public read-only members, but the underlying struct is bigger, - * so you must not copy this struct. - */ - - -/** - * GTime: - * - * Simply a replacement for `time_t`. It has been deprecated - * since it is not equivalent to `time_t` on 64-bit platforms - * with a 64-bit `time_t`. - * - * Unrelated to #GTimer. - * - * Note that #GTime is defined to always be a 32-bit integer, - * unlike `time_t` which may be 64-bit on some systems. Therefore, - * #GTime will overflow in the year 2038, and you cannot use the - * address of a #GTime variable as argument to the UNIX time() - * function. - * - * Instead, do the following: - * - * |[ - * time_t ttime; - * GTime gtime; - * - * time (&ttime); - * gtime = (GTime)ttime; - * ]| - * - * Deprecated: 2.62: This is not [Y2038-safe](https://en.wikipedia.org/wiki/Year_2038_problem). - * Use #GDateTime or #time_t instead. - */ - - -/** - * GTimeVal: - * @tv_sec: seconds - * @tv_usec: microseconds - * - * Represents a precise time, with seconds and microseconds. - * - * Similar to the struct timeval returned by the `gettimeofday()` - * UNIX system call. - * - * GLib is attempting to unify around the use of 64-bit integers to - * represent microsecond-precision time. As such, this type will be - * removed from a future version of GLib. A consequence of using `glong` for - * `tv_sec` is that on 32-bit systems `GTimeVal` is subject to the year 2038 - * problem. - * - * Deprecated: 2.62: Use #GDateTime or #guint64 instead. - */ - - -/** - * GTimeZone: - * - * #GTimeZone is an opaque structure whose members cannot be accessed - * directly. - * - * Since: 2.26 - */ - - -/** - * GTimer: - * - * Opaque datatype that records a start time. - */ - - -/** - * GTokenType: - * @G_TOKEN_EOF: the end of the file - * @G_TOKEN_LEFT_PAREN: a '(' character - * @G_TOKEN_LEFT_CURLY: a '{' character - * @G_TOKEN_LEFT_BRACE: a '[' character - * @G_TOKEN_RIGHT_CURLY: a '}' character - * @G_TOKEN_RIGHT_PAREN: a ')' character - * @G_TOKEN_RIGHT_BRACE: a ']' character - * @G_TOKEN_EQUAL_SIGN: a '=' character - * @G_TOKEN_COMMA: a ',' character - * @G_TOKEN_NONE: not a token - * @G_TOKEN_ERROR: an error occurred - * @G_TOKEN_CHAR: a character - * @G_TOKEN_BINARY: a binary integer - * @G_TOKEN_OCTAL: an octal integer - * @G_TOKEN_INT: an integer - * @G_TOKEN_HEX: a hex integer - * @G_TOKEN_FLOAT: a floating point number - * @G_TOKEN_STRING: a string - * @G_TOKEN_SYMBOL: a symbol - * @G_TOKEN_IDENTIFIER: an identifier - * @G_TOKEN_IDENTIFIER_NULL: a null identifier - * @G_TOKEN_COMMENT_SINGLE: one line comment - * @G_TOKEN_COMMENT_MULTI: multi line comment - * - * The possible types of token returned from each - * g_scanner_get_next_token() call. - */ - - -/** - * GTokenValue: - * @v_symbol: token symbol value - * @v_identifier: token identifier value - * @v_binary: token binary integer value - * @v_octal: octal integer value - * @v_int: integer value - * @v_int64: 64-bit integer value - * @v_float: floating point value - * @v_hex: hex integer value - * @v_string: string value - * @v_comment: comment value - * @v_char: character value - * @v_error: error value - * - * A union holding the value of the token. - */ - - -/** - * GTrashStack: - * @next: pointer to the previous element of the stack, - * gets stored in the first `sizeof (gpointer)` - * bytes of the element - * - * Each piece of memory that is pushed onto the stack - * is cast to a GTrashStack*. - * - * Deprecated: 2.48: #GTrashStack is deprecated without replacement - */ - - -/** - * GTraverseFlags: - * @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has - * been introduced in 2.6, for older version use - * %G_TRAVERSE_LEAFS. - * @G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This - * name has been introduced in 2.6, for older - * version use %G_TRAVERSE_NON_LEAFS. - * @G_TRAVERSE_ALL: all nodes should be visited. - * @G_TRAVERSE_MASK: a mask of all traverse flags. - * @G_TRAVERSE_LEAFS: identical to %G_TRAVERSE_LEAVES. - * @G_TRAVERSE_NON_LEAFS: identical to %G_TRAVERSE_NON_LEAVES. - * - * Specifies which nodes are visited during several of the tree - * functions, including g_node_traverse() and g_node_find(). - */ - - -/** - * GTraverseFunc: - * @key: a key of a #GTree node - * @value: the value corresponding to the key - * @data: user data passed to g_tree_traverse() - * - * Specifies the type of function passed to g_tree_traverse(). It is - * passed the key and value of each node, together with the @user_data - * parameter passed to g_tree_traverse(). If the function returns - * %TRUE, the traversal is stopped. - * - * Returns: %TRUE to stop the traversal - */ - - -/** - * GTraverseType: - * @G_IN_ORDER: vists a node's left child first, then the node itself, - * then its right child. This is the one to use if you - * want the output sorted according to the compare - * function. - * @G_PRE_ORDER: visits a node, then its children. - * @G_POST_ORDER: visits the node's children, then the node itself. - * @G_LEVEL_ORDER: is not implemented for - * [balanced binary trees][glib-Balanced-Binary-Trees]. - * For [n-ary trees][glib-N-ary-Trees], it - * vists the root node first, then its children, then - * its grandchildren, and so on. Note that this is less - * efficient than the other orders. - * - * Specifies the type of traversal performed by g_tree_traverse(), - * g_node_traverse() and g_node_find(). The different orders are - * illustrated here: - * - In order: A, B, C, D, E, F, G, H, I - * ![](Sorted_binary_tree_inorder.svg) - * - Pre order: F, B, A, D, C, E, G, I, H - * ![](Sorted_binary_tree_preorder.svg) - * - Post order: A, C, E, D, B, H, I, G, F - * ![](Sorted_binary_tree_postorder.svg) - * - Level order: F, B, G, A, D, I, C, E, H - * ![](Sorted_binary_tree_breadth-first_traversal.svg) - */ - - -/** - * GTree: - * - * The GTree struct is an opaque data structure representing a - * [balanced binary tree][glib-Balanced-Binary-Trees]. It should be - * accessed only by using the following functions. - */ - - -/** - * GUINT16_FROM_BE: - * @val: a #guint16 value in big-endian byte order - * - * Converts a #guint16 value from big-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GUINT16_FROM_LE: - * @val: a #guint16 value in little-endian byte order - * - * Converts a #guint16 value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GUINT16_SWAP_BE_PDP: - * @val: a #guint16 value in big-endian or pdp-endian byte order - * - * Converts a #guint16 value between big-endian and pdp-endian byte order. - * The conversion is symmetric so it can be used both ways. - * - * Returns: @val converted to the opposite byte order - */ - - -/** - * GUINT16_SWAP_LE_BE: - * @val: a #guint16 value in little-endian or big-endian byte order - * - * Converts a #guint16 value between little-endian and big-endian byte order. - * The conversion is symmetric so it can be used both ways. - * - * Returns: @val converted to the opposite byte order - */ - - -/** - * GUINT16_SWAP_LE_PDP: - * @val: a #guint16 value in little-endian or pdp-endian byte order - * - * Converts a #guint16 value between little-endian and pdp-endian byte order. - * The conversion is symmetric so it can be used both ways. - * - * Returns: @val converted to the opposite byte order - */ - - -/** - * GUINT16_TO_BE: - * @val: a #guint16 value in host byte order - * - * Converts a #guint16 value from host byte order to big-endian. - * - * Returns: @val converted to big-endian - */ - - -/** - * GUINT16_TO_LE: - * @val: a #guint16 value in host byte order - * - * Converts a #guint16 value from host byte order to little-endian. - * - * Returns: @val converted to little-endian - */ - - -/** - * GUINT32_FROM_BE: - * @val: a #guint32 value in big-endian byte order - * - * Converts a #guint32 value from big-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GUINT32_FROM_LE: - * @val: a #guint32 value in little-endian byte order - * - * Converts a #guint32 value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GUINT32_SWAP_BE_PDP: - * @val: a #guint32 value in big-endian or pdp-endian byte order - * - * Converts a #guint32 value between big-endian and pdp-endian byte order. - * The conversion is symmetric so it can be used both ways. - * - * Returns: @val converted to the opposite byte order - */ - - -/** - * GUINT32_SWAP_LE_BE: - * @val: a #guint32 value in little-endian or big-endian byte order - * - * Converts a #guint32 value between little-endian and big-endian byte order. - * The conversion is symmetric so it can be used both ways. - * - * Returns: @val converted to the opposite byte order - */ - - -/** - * GUINT32_SWAP_LE_PDP: - * @val: a #guint32 value in little-endian or pdp-endian byte order - * - * Converts a #guint32 value between little-endian and pdp-endian byte order. - * The conversion is symmetric so it can be used both ways. - * - * Returns: @val converted to the opposite byte order - */ - - -/** - * GUINT32_TO_BE: - * @val: a #guint32 value in host byte order - * - * Converts a #guint32 value from host byte order to big-endian. - * - * Returns: @val converted to big-endian - */ - - -/** - * GUINT32_TO_LE: - * @val: a #guint32 value in host byte order - * - * Converts a #guint32 value from host byte order to little-endian. - * - * Returns: @val converted to little-endian - */ - - -/** - * GUINT64_FROM_BE: - * @val: a #guint64 value in big-endian byte order - * - * Converts a #guint64 value from big-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GUINT64_FROM_LE: - * @val: a #guint64 value in little-endian byte order - * - * Converts a #guint64 value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GUINT64_SWAP_LE_BE: - * @val: a #guint64 value in little-endian or big-endian byte order - * - * Converts a #guint64 value between little-endian and big-endian byte order. - * The conversion is symmetric so it can be used both ways. - * - * Returns: @val converted to the opposite byte order - */ - - -/** - * GUINT64_TO_BE: - * @val: a #guint64 value in host byte order - * - * Converts a #guint64 value from host byte order to big-endian. - * - * Returns: @val converted to big-endian - */ - - -/** - * GUINT64_TO_LE: - * @val: a #guint64 value in host byte order - * - * Converts a #guint64 value from host byte order to little-endian. - * - * Returns: @val converted to little-endian - */ - - -/** - * GUINT_FROM_BE: - * @val: a #guint value in big-endian byte order - * - * Converts a #guint value from big-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GUINT_FROM_LE: - * @val: a #guint value in little-endian byte order - * - * Converts a #guint value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GUINT_TO_BE: - * @val: a #guint value in host byte order - * - * Converts a #guint value from host byte order to big-endian. - * - * Returns: @val converted to big-endian byte order - */ - - -/** - * GUINT_TO_LE: - * @val: a #guint value in host byte order - * - * Converts a #guint value from host byte order to little-endian. - * - * Returns: @val converted to little-endian byte order. - */ - - -/** - * GUINT_TO_POINTER: - * @u: unsigned integer to stuff into the pointer - * - * Stuffs an unsigned integer into a pointer type. - */ - - -/** - * GULONG_FROM_BE: - * @val: a #gulong value in big-endian byte order - * - * Converts a #gulong value from big-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GULONG_FROM_LE: - * @val: a #gulong value in little-endian byte order - * - * Converts a #gulong value from little-endian to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * GULONG_TO_BE: - * @val: a #gulong value in host byte order - * - * Converts a #gulong value from host byte order to big-endian. - * - * Returns: @val converted to big-endian - */ - - -/** - * GULONG_TO_LE: - * @val: a #gulong value in host byte order - * - * Converts a #gulong value from host byte order to little-endian. - * - * Returns: @val converted to little-endian - */ - - -/** - * GUri: - * - * A parsed absolute URI. - * - * Since #GUri only represents absolute URIs, all #GUris will have a - * URI scheme, so g_uri_get_scheme() will always return a non-%NULL - * answer. Likewise, by definition, all URIs have a path component, so - * g_uri_get_path() will always return a non-%NULL string (which may be empty). - * - * If the URI string has an - * [‘authority’ component](https://tools.ietf.org/html/rfc3986#section-3) (that - * is, if the scheme is followed by `://` rather than just `:`), then the - * #GUri will contain a hostname, and possibly a port and ‘userinfo’. - * Additionally, depending on how the #GUri was constructed/parsed (for example, - * using the %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS flags), - * the userinfo may be split out into a username, password, and - * additional authorization-related parameters. - * - * Normally, the components of a #GUri will have all `%`-encoded - * characters decoded. However, if you construct/parse a #GUri with - * %G_URI_FLAGS_ENCODED, then the `%`-encoding will be preserved instead in - * the userinfo, path, and query fields (and in the host field if also - * created with %G_URI_FLAGS_NON_DNS). In particular, this is necessary if - * the URI may contain binary data or non-UTF-8 text, or if decoding - * the components might change the interpretation of the URI. - * - * For example, with the encoded flag: - * - * |[ - * g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_ENCODED, &err); - * g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue"); - * ]| - * - * While the default `%`-decoding behaviour would give: - * - * |[ - * g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_NONE, &err); - * g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http://host/path?param=value"); - * ]| - * - * During decoding, if an invalid UTF-8 string is encountered, parsing will fail - * with an error indicating the bad string location: - * - * |[ - * g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fbad%3D%00alue", G_URI_FLAGS_NONE, &err); - * g_assert_error (err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY); - * ]| - * - * You should pass %G_URI_FLAGS_ENCODED or %G_URI_FLAGS_ENCODED_QUERY if you - * need to handle that case manually. In particular, if the query string - * contains `=` characters that are `%`-encoded, you should let - * g_uri_parse_params() do the decoding once of the query. - * - * #GUri is immutable once constructed, and can safely be accessed from - * multiple threads. Its reference counting is atomic. - * - * Since: 2.66 - */ - - -/** - * GUriParamsIter: - * - * Many URI schemes include one or more attribute/value pairs as part of the URI - * value. For example `scheme://server/path?query=string&is=there` has two - * attributes – `query=string` and `is=there` – in its query part. - * - * A #GUriParamsIter structure represents an iterator that can be used to - * iterate over the attribute/value pairs of a URI query string. #GUriParamsIter - * structures are typically allocated on the stack and then initialized with - * g_uri_params_iter_init(). See the documentation for g_uri_params_iter_init() - * for a usage example. - * - * Since: 2.66 - */ - - -/** - * GVariant: - * - * #GVariant is an opaque data structure and can only be accessed - * using the following functions. - * - * Since: 2.24 - */ - - -/** - * GVariantBuilder: - * - * A utility type for constructing container-type #GVariant instances. - * - * This is an opaque structure and may only be accessed using the - * following functions. - * - * #GVariantBuilder is not threadsafe in any way. Do not attempt to - * access it from more than one thread. - */ - - -/** - * GVariantClass: - * @G_VARIANT_CLASS_BOOLEAN: The #GVariant is a boolean. - * @G_VARIANT_CLASS_BYTE: The #GVariant is a byte. - * @G_VARIANT_CLASS_INT16: The #GVariant is a signed 16 bit integer. - * @G_VARIANT_CLASS_UINT16: The #GVariant is an unsigned 16 bit integer. - * @G_VARIANT_CLASS_INT32: The #GVariant is a signed 32 bit integer. - * @G_VARIANT_CLASS_UINT32: The #GVariant is an unsigned 32 bit integer. - * @G_VARIANT_CLASS_INT64: The #GVariant is a signed 64 bit integer. - * @G_VARIANT_CLASS_UINT64: The #GVariant is an unsigned 64 bit integer. - * @G_VARIANT_CLASS_HANDLE: The #GVariant is a file handle index. - * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating - * point value. - * @G_VARIANT_CLASS_STRING: The #GVariant is a normal string. - * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path - * string. - * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a D-Bus signature string. - * @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant. - * @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value. - * @G_VARIANT_CLASS_ARRAY: The #GVariant is an array. - * @G_VARIANT_CLASS_TUPLE: The #GVariant is a tuple. - * @G_VARIANT_CLASS_DICT_ENTRY: The #GVariant is a dictionary entry. - * - * The range of possible top-level types of #GVariant instances. - * - * Since: 2.24 - */ - - -/** - * GVariantDict: - * - * #GVariantDict is a mutable interface to #GVariant dictionaries. - * - * It can be used for doing a sequence of dictionary lookups in an - * efficient way on an existing #GVariant dictionary or it can be used - * to construct new dictionaries with a hashtable-like interface. It - * can also be used for taking existing dictionaries and modifying them - * in order to create new ones. - * - * #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT - * dictionaries. - * - * It is possible to use #GVariantDict allocated on the stack or on the - * heap. When using a stack-allocated #GVariantDict, you begin with a - * call to g_variant_dict_init() and free the resources with a call to - * g_variant_dict_clear(). - * - * Heap-allocated #GVariantDict follows normal refcounting rules: you - * allocate it with g_variant_dict_new() and use g_variant_dict_ref() - * and g_variant_dict_unref(). - * - * g_variant_dict_end() is used to convert the #GVariantDict back into a - * dictionary-type #GVariant. When used with stack-allocated instances, - * this also implicitly frees all associated memory, but for - * heap-allocated instances, you must still call g_variant_dict_unref() - * afterwards. - * - * You will typically want to use a heap-allocated #GVariantDict when - * you expose it as part of an API. For most other uses, the - * stack-allocated form will be more convenient. - * - * Consider the following two examples that do the same thing in each - * style: take an existing dictionary and look up the "count" uint32 - * key, adding 1 to it if it is found, or returning an error if the - * key is not found. Each returns the new dictionary as a floating - * #GVariant. - * - * ## Using a stack-allocated GVariantDict - * - * |[ - * GVariant * - * add_to_count (GVariant *orig, - * GError **error) - * { - * GVariantDict dict; - * guint32 count; - * - * g_variant_dict_init (&dict, orig); - * if (!g_variant_dict_lookup (&dict, "count", "u", &count)) - * { - * g_set_error (...); - * g_variant_dict_clear (&dict); - * return NULL; - * } - * - * g_variant_dict_insert (&dict, "count", "u", count + 1); - * - * return g_variant_dict_end (&dict); - * } - * ]| - * - * ## Using heap-allocated GVariantDict - * - * |[ - * GVariant * - * add_to_count (GVariant *orig, - * GError **error) - * { - * GVariantDict *dict; - * GVariant *result; - * guint32 count; - * - * dict = g_variant_dict_new (orig); - * - * if (g_variant_dict_lookup (dict, "count", "u", &count)) - * { - * g_variant_dict_insert (dict, "count", "u", count + 1); - * result = g_variant_dict_end (dict); - * } - * else - * { - * g_set_error (...); - * result = NULL; - * } - * - * g_variant_dict_unref (dict); - * - * return result; - * } - * ]| - * - * Since: 2.40 - */ - - -/** - * GVariantIter: (skip) - * - * #GVariantIter is an opaque data structure and can only be accessed - * using the following functions. - */ - - -/** - * GVariantParseError: - * @G_VARIANT_PARSE_ERROR_FAILED: generic error (unused) - * @G_VARIANT_PARSE_ERROR_BASIC_TYPE_EXPECTED: a non-basic #GVariantType was given where a basic type was expected - * @G_VARIANT_PARSE_ERROR_CANNOT_INFER_TYPE: cannot infer the #GVariantType - * @G_VARIANT_PARSE_ERROR_DEFINITE_TYPE_EXPECTED: an indefinite #GVariantType was given where a definite type was expected - * @G_VARIANT_PARSE_ERROR_INPUT_NOT_AT_END: extra data after parsing finished - * @G_VARIANT_PARSE_ERROR_INVALID_CHARACTER: invalid character in number or unicode escape - * @G_VARIANT_PARSE_ERROR_INVALID_FORMAT_STRING: not a valid #GVariant format string - * @G_VARIANT_PARSE_ERROR_INVALID_OBJECT_PATH: not a valid object path - * @G_VARIANT_PARSE_ERROR_INVALID_SIGNATURE: not a valid type signature - * @G_VARIANT_PARSE_ERROR_INVALID_TYPE_STRING: not a valid #GVariant type string - * @G_VARIANT_PARSE_ERROR_NO_COMMON_TYPE: could not find a common type for array entries - * @G_VARIANT_PARSE_ERROR_NUMBER_OUT_OF_RANGE: the numerical value is out of range of the given type - * @G_VARIANT_PARSE_ERROR_NUMBER_TOO_BIG: the numerical value is out of range for any type - * @G_VARIANT_PARSE_ERROR_TYPE_ERROR: cannot parse as variant of the specified type - * @G_VARIANT_PARSE_ERROR_UNEXPECTED_TOKEN: an unexpected token was encountered - * @G_VARIANT_PARSE_ERROR_UNKNOWN_KEYWORD: an unknown keyword was encountered - * @G_VARIANT_PARSE_ERROR_UNTERMINATED_STRING_CONSTANT: unterminated string constant - * @G_VARIANT_PARSE_ERROR_VALUE_EXPECTED: no value given - * @G_VARIANT_PARSE_ERROR_RECURSION: variant was too deeply nested; #GVariant is only guaranteed to handle nesting up to 64 levels (Since: 2.64) - * - * Error codes returned by parsing text-format GVariants. - */ - - -/** - * G_APPROX_VALUE: - * @a: a numeric value - * @b: a numeric value - * @epsilon: a numeric value that expresses the tolerance between @a and @b - * - * Evaluates to a truth value if the absolute difference between @a and @b is - * smaller than @epsilon, and to a false value otherwise. - * - * For example, - * - `G_APPROX_VALUE (5, 6, 2)` evaluates to true - * - `G_APPROX_VALUE (3.14, 3.15, 0.001)` evaluates to false - * - `G_APPROX_VALUE (n, 0.f, FLT_EPSILON)` evaluates to true if `n` is within - * the single precision floating point epsilon from zero - * - * Returns: %TRUE if the two values are within the desired range - * Since: 2.58 - */ - - -/** - * G_ASCII_DTOSTR_BUF_SIZE: - * - * A good size for a buffer to be passed into g_ascii_dtostr(). - * It is guaranteed to be enough for all output of that function - * on systems with 64bit IEEE-compatible doubles. - * - * The typical usage would be something like: - * |[ - * char buf[G_ASCII_DTOSTR_BUF_SIZE]; - * - * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); - * ]| - */ - - -/** - * G_ATOMIC_LOCK_FREE: - * - * This macro is defined if the atomic operations of GLib are - * implemented using real hardware atomic operations. This means that - * the GLib atomic API can be used between processes and safely mixed - * with other (hardware) atomic APIs. - * - * If this macro is not defined, the atomic operations may be - * emulated using a mutex. In that case, the GLib atomic operations are - * only atomic relative to themselves and within a single process. - */ - - -/** - * G_BEGIN_DECLS: - * - * Used (along with #G_END_DECLS) to bracket header files. If the - * compiler in use is a C++ compiler, adds extern "C" - * around the header. - */ - - -/** - * G_BIG_ENDIAN: - * - * Specifies one of the possible types of byte order. - * See #G_BYTE_ORDER. - */ - - -/** - * G_BYTE_ORDER: - * - * The host byte order. - * This can be either #G_LITTLE_ENDIAN or #G_BIG_ENDIAN (support for - * #G_PDP_ENDIAN may be added in future.) - */ - - -/** - * G_CSET_A_2_Z: - * - * The set of uppercase ASCII alphabet characters. - * Used for specifying valid identifier characters - * in #GScannerConfig. - */ - - -/** - * G_CSET_DIGITS: - * - * The set of ASCII digits. - * Used for specifying valid identifier characters - * in #GScannerConfig. - */ - - -/** - * G_CSET_LATINC: - * - * The set of uppercase ISO 8859-1 alphabet characters - * which are not ASCII characters. - * Used for specifying valid identifier characters - * in #GScannerConfig. - */ - - -/** - * G_CSET_LATINS: - * - * The set of lowercase ISO 8859-1 alphabet characters - * which are not ASCII characters. - * Used for specifying valid identifier characters - * in #GScannerConfig. - */ - - -/** - * G_CSET_a_2_z: - * - * The set of lowercase ASCII alphabet characters. - * Used for specifying valid identifier characters - * in #GScannerConfig. - */ - - -/** - * G_DATE_BAD_DAY: - * - * Represents an invalid #GDateDay. - */ - - -/** - * G_DATE_BAD_JULIAN: - * - * Represents an invalid Julian day number. - */ - - -/** - * G_DATE_BAD_YEAR: - * - * Represents an invalid year. - */ - - -/** - * G_DEFINE_AUTOPTR_CLEANUP_FUNC: - * @TypeName: a type name to define a g_autoptr() cleanup function for - * @func: the cleanup function - * - * Defines the appropriate cleanup function for a pointer type. - * - * The function will not be called if the variable to be cleaned up - * contains %NULL. - * - * This will typically be the `_free()` or `_unref()` function for the given - * type. - * - * With this definition, it will be possible to use g_autoptr() with - * @TypeName. - * - * |[ - * G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref) - * ]| - * - * This macro should be used unconditionally; it is a no-op on compilers - * where cleanup is not supported. - * - * Since: 2.44 - */ - - -/** - * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC: - * @TypeName: a type name to define a g_auto() cleanup function for - * @func: the clear function - * - * Defines the appropriate cleanup function for a type. - * - * This will typically be the `_clear()` function for the given type. - * - * With this definition, it will be possible to use g_auto() with - * @TypeName. - * - * |[ - * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear) - * ]| - * - * This macro should be used unconditionally; it is a no-op on compilers - * where cleanup is not supported. - * - * Since: 2.44 - */ - - -/** - * G_DEFINE_AUTO_CLEANUP_FREE_FUNC: - * @TypeName: a type name to define a g_auto() cleanup function for - * @func: the free function - * @none: the "none" value for the type - * - * Defines the appropriate cleanup function for a type. - * - * With this definition, it will be possible to use g_auto() with - * @TypeName. - * - * This function will be rarely used. It is used with pointer-based - * typedefs and non-pointer types where the value of the variable - * represents a resource that must be freed. Two examples are #GStrv - * and file descriptors. - * - * @none specifies the "none" value for the type in question. It is - * probably something like %NULL or `-1`. If the variable is found to - * contain this value then the free function will not be called. - * - * |[ - * G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL) - * ]| - * - * This macro should be used unconditionally; it is a no-op on compilers - * where cleanup is not supported. - * - * Since: 2.44 - */ - - -/** - * G_DEFINE_QUARK: - * @QN: the name to return a #GQuark for - * @q_n: prefix for the function name - * - * A convenience macro which defines a function returning the - * #GQuark for the name @QN. The function will be named - * @q_n_quark(). - * - * Note that the quark name will be stringified automatically - * in the macro, so you shouldn't use double quotes. - * - * Since: 2.34 - */ - - -/** - * G_DEPRECATED: - * - * This macro is similar to %G_GNUC_DEPRECATED, and can be used to mark - * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED, it is - * meant to be portable across different compilers and must be placed - * before the function declaration. - * - * |[ - * gint16 in; - * gint32 out; - * sscanf ("42", "%" G_GINT16_FORMAT, &in) - * out = in * 1000; - * g_print ("%" G_GINT32_FORMAT, out); - * ]| - */ - - -/** - * G_GINT16_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gint16 or #guint16. It - * is a string literal, but doesn't include the percent-sign, such - * that you can add precision and length modifiers between percent-sign - * and conversion specifier and append a conversion specifier. - * - * The following example prints "0x7b"; - * |[ - * gint16 value = 123; - * g_print ("%#" G_GINT16_MODIFIER "x", value); - * ]| - * - * Since: 2.4 - */ - - -/** - * G_GINT32_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #gint32. See also #G_GINT16_FORMAT. - */ - - -/** - * G_GINT32_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gint32 or #guint32. It - * is a string literal. See also #G_GINT16_MODIFIER. - * - * Since: 2.4 - */ - - -/** - * G_GINT64_CONSTANT: - * @val: a literal integer value, e.g. 0x1d636b02300a7aa7 - * - * This macro is used to insert 64-bit integer literals - * into the source code. - */ - - -/** - * G_GINT64_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #gint64. See also #G_GINT16_FORMAT. - * - * Some platforms do not support scanning and printing 64-bit integers, - * even though the types are supported. On such platforms %G_GINT64_FORMAT - * is not defined. Note that scanf() may not support 64-bit integers, even - * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() - * is not recommended for parsing anyway; consider using g_ascii_strtoull() - * instead. - */ - - -/** - * G_GINT64_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gint64 or #guint64. - * It is a string literal. - * - * Some platforms do not support printing 64-bit integers, even - * though the types are supported. On such platforms %G_GINT64_MODIFIER - * is not defined. - * - * Since: 2.4 - */ - - -/** - * G_GINTPTR_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #gintptr. - * - * Since: 2.22 - */ - - -/** - * G_GINTPTR_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gintptr or #guintptr. - * It is a string literal. - * - * Since: 2.22 - */ - - -/** - * G_GNUC_BEGIN_IGNORE_DEPRECATIONS: - * - * Tells gcc (if it is a new enough version) to temporarily stop emitting - * warnings when functions marked with %G_GNUC_DEPRECATED or - * %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have - * one deprecated function calling another one, or when you still have - * regression tests for deprecated functions. - * - * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you - * are not compiling with `-Wdeprecated-declarations` then neither macro - * has any effect.) - * - * This macro can be used either inside or outside of a function body, - * but must appear on a line by itself. Both this macro and the corresponding - * %G_GNUC_END_IGNORE_DEPRECATIONS are considered statements, so they - * should not be used around branching or loop conditions; for instance, - * this use is invalid: - * - * |[ - * G_GNUC_BEGIN_IGNORE_DEPRECATIONS - * if (check == some_deprecated_function ()) - * G_GNUC_END_IGNORE_DEPRECATIONS - * { - * do_something (); - * } - * ]| - * - * and you should move the deprecated section outside the condition - * - * |[ - * - * // Solution A - * some_data_t *res; - * - * G_GNUC_BEGIN_IGNORE_DEPRECATIONS - * res = some_deprecated_function (); - * G_GNUC_END_IGNORE_DEPRECATIONS - * - * if (check == res) - * { - * do_something (); - * } - * - * // Solution B - * G_GNUC_BEGIN_IGNORE_DEPRECATIONS - * if (check == some_deprecated_function ()) - * { - * do_something (); - * } - * G_GNUC_END_IGNORE_DEPRECATIONS - * ]| - * - * |[ - * #if G_GNUC_CHECK_VERSION(4, 8) - * #endif - * ]| - * - * Since: 2.42 - */ - - -/** - * G_GNUC_END_IGNORE_DEPRECATIONS: - * - * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling - * gcc to begin outputting warnings again (assuming those warnings - * had been enabled to begin with). - * - * This macro can be used either inside or outside of a function body, - * but must appear on a line by itself. - * - * Since: 2.32 - */ - - -/** - * G_GNUC_EXTENSION: - * - * Expands to __extension__ when gcc is used as the compiler. This simply - * tells gcc not to warn about the following non-standard code when compiling - * with the `-pedantic` option. - */ - - -/** - * G_GNUC_INTERNAL: - * - * This attribute can be used for marking library functions as being used - * internally to the library only, which may allow the compiler to handle - * function calls more efficiently. Note that static functions do not need - * to be marked as internal in this way. See the GNU C documentation for - * details. - * - * When using a compiler that supports the GNU C hidden visibility attribute, - * this macro expands to __attribute__((visibility("hidden"))). - * When using the Sun Studio compiler, it expands to __hidden. - * - * Note that for portability, the attribute should be placed before the - * function declaration. While GCC allows the macro after the declaration, - * Sun Studio does not. - * - * |[ - * G_GNUC_INTERNAL - * void _g_log_fallback_handler (const gchar *log_domain, - * GLogLevelFlags log_level, - * const gchar *message, - * gpointer unused_data); - * ]| - * - * Since: 2.6 - */ - - -/** - * G_GOFFSET_CONSTANT: - * @val: a literal integer value, e.g. 0x1d636b02300a7aa7 - * - * This macro is used to insert #goffset 64-bit integer literals - * into the source code. - * - * See also #G_GINT64_CONSTANT. - * - * Since: 2.20 - */ - - -/** - * G_GOFFSET_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #goffset. See also #G_GINT64_FORMAT. - * - * Since: 2.20 - */ - - -/** - * G_GOFFSET_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #goffset. It is a string - * literal. See also #G_GINT64_MODIFIER. - * - * Since: 2.20 - */ - - -/** - * G_GSIZE_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #gsize. See also #G_GINT16_FORMAT. - * - * Since: 2.6 - */ - - -/** - * G_GSIZE_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gsize. It - * is a string literal. - * - * Since: 2.6 - */ - - -/** - * G_GSSIZE_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #gssize. See also #G_GINT16_FORMAT. - * - * Since: 2.6 - */ - - -/** - * G_GSSIZE_MODIFIER: - * - * The platform dependent length modifier for conversion specifiers - * for scanning and printing values of type #gssize. It - * is a string literal. - * - * Since: 2.6 - */ - - -/** - * G_GUINT16_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #guint16. See also #G_GINT16_FORMAT - */ - - -/** - * G_GUINT32_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #guint32. See also #G_GINT16_FORMAT. - */ - - -/** - * G_GUINT64_CONSTANT: - * @val: a literal integer value, e.g. 0x1d636b02300a7aa7U - * - * This macro is used to insert 64-bit unsigned integer - * literals into the source code. - * - * Since: 2.10 - */ - - -/** - * G_GUINT64_FORMAT: - * - * This is the platform dependent conversion specifier for scanning - * and printing values of type #guint64. See also #G_GINT16_FORMAT. - * - * Some platforms do not support scanning and printing 64-bit integers, - * even though the types are supported. On such platforms %G_GUINT64_FORMAT - * is not defined. Note that scanf() may not support 64-bit integers, even - * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() - * is not recommended for parsing anyway; consider using g_ascii_strtoull() - * instead. - */ - - -/** - * G_GUINTPTR_FORMAT: - * - * This is the platform dependent conversion specifier - * for scanning and printing values of type #guintptr. - * - * Since: 2.22 - */ - - -/** - * G_HAVE_GNUC_VISIBILITY: - * - * Defined to 1 if gcc-style visibility handling is supported. - */ - - -/** - * G_HOOK: - * @hook: a pointer - * - * Casts a pointer to a `GHook*`. - */ - - -/** - * G_HOOK_ACTIVE: - * @hook: a #GHook - * - * Returns %TRUE if the #GHook is active, which is normally the case - * until the #GHook is destroyed. - * - * Returns: %TRUE if the #GHook is active - */ - - -/** - * G_HOOK_FLAGS: - * @hook: a #GHook - * - * Gets the flags of a hook. - */ - - -/** - * G_HOOK_FLAG_USER_SHIFT: - * - * The position of the first bit which is not reserved for internal - * use be the #GHook implementation, i.e. - * `1 << G_HOOK_FLAG_USER_SHIFT` is the first - * bit which can be used for application-defined flags. - */ - - -/** - * G_HOOK_IN_CALL: - * @hook: a #GHook - * - * Returns %TRUE if the #GHook function is currently executing. - * - * Returns: %TRUE if the #GHook function is currently executing - */ - - -/** - * G_HOOK_IS_UNLINKED: - * @hook: a #GHook - * - * Returns %TRUE if the #GHook is not in a #GHookList. - * - * Returns: %TRUE if the #GHook is not in a #GHookList - */ - - -/** - * G_HOOK_IS_VALID: - * @hook: a #GHook - * - * Returns %TRUE if the #GHook is valid, i.e. it is in a #GHookList, - * it is active and it has not been destroyed. - * - * Returns: %TRUE if the #GHook is valid - */ - - -/** - * G_IEEE754_DOUBLE_BIAS: - * - * The bias by which exponents in double-precision floats are offset. - */ - - -/** - * G_IEEE754_FLOAT_BIAS: - * - * The bias by which exponents in single-precision floats are offset. - */ - - -/** - * G_IO_CHANNEL_ERROR: - * - * Error domain for #GIOChannel operations. Errors in this domain will - * be from the #GIOChannelError enumeration. See #GError for - * information on error domains. - */ - - -/** - * G_IS_DIR_SEPARATOR: - * @c: a character - * - * Checks whether a character is a directory - * separator. It returns %TRUE for '/' on UNIX - * machines and for '\' or '/' under Windows. - * - * Since: 2.6 - */ - - -/** - * G_KEY_FILE_DESKTOP_GROUP: - * - * The name of the main group of a desktop entry file, as defined in the - * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec). - * Consult the specification for more - * details about the meanings of the keys below. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_ACTIONS: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string list - * giving the available application actions. - * - * Since: 2.38 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_CATEGORIES: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list - * of strings giving the categories in which the desktop entry - * should be shown in a menu. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_COMMENT: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized - * string giving the tooltip for the desktop entry. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean - * set to true if the application is D-Bus activatable. - * - * Since: 2.38 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_EXEC: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string - * giving the command line to execute. It is only valid for desktop - * entries with the `Application` type. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized - * string giving the generic name of the desktop entry. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_HIDDEN: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean - * stating whether the desktop entry has been deleted by the user. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_ICON: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized - * string giving the name of the icon to be displayed for the desktop - * entry. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_MIME_TYPE: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list - * of strings giving the MIME types supported by this desktop entry. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_NAME: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized - * string giving the specific name of the desktop entry. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of - * strings identifying the environments that should not display the - * desktop entry. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean - * stating whether the desktop entry should be shown in menus. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of - * strings identifying the environments that should display the - * desktop entry. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_PATH: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string - * containing the working directory to run the program in. It is only - * valid for desktop entries with the `Application` type. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean - * stating whether the application supports the - * [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is string - * identifying the WM class or name hint of a window that the application - * will create, which can be used to emulate Startup Notification with - * older applications. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_TERMINAL: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean - * stating whether the program should be run in a terminal window. - * - * It is only valid for desktop entries with the `Application` type. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_TRY_EXEC: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string - * giving the file name of a binary on disk used to determine if the - * program is actually installed. It is only valid for desktop entries - * with the `Application` type. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_TYPE: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string - * giving the type of the desktop entry. - * - * Usually %G_KEY_FILE_DESKTOP_TYPE_APPLICATION, - * %G_KEY_FILE_DESKTOP_TYPE_LINK, or - * %G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_URL: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string - * giving the URL to access. It is only valid for desktop entries - * with the `Link` type. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_KEY_VERSION: - * - * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string - * giving the version of the Desktop Entry Specification used for - * the desktop entry file. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_TYPE_APPLICATION: - * - * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop - * entries representing applications. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_TYPE_DIRECTORY: - * - * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop - * entries representing directories. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_DESKTOP_TYPE_LINK: - * - * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop - * entries representing links to documents. - * - * Since: 2.14 - */ - - -/** - * G_KEY_FILE_ERROR: - * - * Error domain for key file parsing. Errors in this domain will - * be from the #GKeyFileError enumeration. - * - * See #GError for information on error domains. - */ - - -/** - * G_LIKELY: - * @expr: the expression - * - * Hints the compiler that the expression is likely to evaluate to - * a true value. The compiler may use this information for optimizations. - * - * |[ - * if (G_LIKELY (random () != 1)) - * g_print ("not one"); - * ]| - * - * Returns: the value of @expr - * Since: 2.2 - */ - - -/** - * G_LITTLE_ENDIAN: - * - * Specifies one of the possible types of byte order. - * See #G_BYTE_ORDER. - */ - - -/** - * G_LN10: - * - * The natural logarithm of 10. - */ - - -/** - * G_LN2: - * - * The natural logarithm of 2. - */ - - -/** - * G_LOCK: - * @name: the name of the lock - * - * Works like g_mutex_lock(), but for a lock defined with - * %G_LOCK_DEFINE. - */ - - -/** - * G_LOCK_DEFINE: - * @name: the name of the lock - * - * The `G_LOCK_` macros provide a convenient interface to #GMutex. - * %G_LOCK_DEFINE defines a lock. It can appear in any place where - * variable definitions may appear in programs, i.e. in the first block - * of a function or outside of functions. The @name parameter will be - * mangled to get the name of the #GMutex. This means that you - * can use names of existing variables as the parameter - e.g. the name - * of the variable you intend to protect with the lock. Look at our - * give_me_next_number() example using the `G_LOCK` macros: - * - * Here is an example for using the `G_LOCK` convenience macros: - * - * |[ - * G_LOCK_DEFINE (current_number); - * - * int - * give_me_next_number (void) - * { - * static int current_number = 0; - * int ret_val; - * - * G_LOCK (current_number); - * ret_val = current_number = calc_next_number (current_number); - * G_UNLOCK (current_number); - * - * return ret_val; - * } - * ]| - */ - - -/** - * G_LOCK_DEFINE_STATIC: - * @name: the name of the lock - * - * This works like %G_LOCK_DEFINE, but it creates a static object. - */ - - -/** - * G_LOCK_EXTERN: - * @name: the name of the lock - * - * This declares a lock, that is defined with %G_LOCK_DEFINE in another - * module. - */ - - -/** - * G_LOG_2_BASE_10: - * - * Multiplying the base 2 exponent by this number yields the base 10 exponent. - */ - - -/** - * G_LOG_DOMAIN: - * - * Defines the log domain. See [Log Domains](#log-domains). - * - * Libraries should define this so that any messages - * which they log can be differentiated from messages from other - * libraries and application code. But be careful not to define - * it in any public header files. - * - * Log domains must be unique, and it is recommended that they are the - * application or library name, optionally followed by a hyphen and a sub-domain - * name. For example, `bloatpad` or `bloatpad-io`. - * - * If undefined, it defaults to the default %NULL (or `""`) log domain; this is - * not advisable, as it cannot be filtered against using the `G_MESSAGES_DEBUG` - * environment variable. - * - * For example, GTK+ uses this in its `Makefile.am`: - * |[ - * AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\" - * ]| - * - * Applications can choose to leave it as the default %NULL (or `""`) - * domain. However, defining the domain offers the same advantages as - * above. - */ - - -/** - * G_LOG_FATAL_MASK: - * - * GLib log levels that are considered fatal by default. - * - * This is not used if structured logging is enabled; see - * [Using Structured Logging][using-structured-logging]. - */ - - -/** - * G_LOG_LEVEL_USER_SHIFT: - * - * Log levels below 1< - * GOnce my_once = G_ONCE_INIT; - * ]| - * - * Since: 2.4 - */ - - -/** - * G_OS_UNIX: - * - * This macro is defined only on UNIX. So you can bracket - * UNIX-specific code in "\#ifdef G_OS_UNIX". - */ - - -/** - * G_OS_WIN32: - * - * This macro is defined only on Windows. So you can bracket - * Windows-specific code in "\#ifdef G_OS_WIN32". - */ - - -/** - * G_PASTE: - * @identifier1: an identifier - * @identifier2: an identifier - * - * Yields a new preprocessor pasted identifier - * @identifier1identifier2 from its expanded - * arguments @identifier1 and @identifier2. For example, - * the following code: - * |[ - * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller) - * const gchar *name = GET (traveller, name); - * const gchar *quest = GET (traveller, quest); - * GdkColor *favourite = GET (traveller, favourite_colour); - * ]| - * - * is transformed by the preprocessor into: - * |[ - * const gchar *name = traveller_get_name (traveller); - * const gchar *quest = traveller_get_quest (traveller); - * GdkColor *favourite = traveller_get_favourite_colour (traveller); - * ]| - * - * Since: 2.20 - */ - - -/** - * G_PDP_ENDIAN: - * - * Specifies one of the possible types of byte order - * (currently unused). See #G_BYTE_ORDER. - */ - - -/** - * G_PI: - * - * The value of pi (ratio of circle's circumference to its diameter). - */ - - -/** - * G_PI_2: - * - * Pi divided by 2. - */ - - -/** - * G_PI_4: - * - * Pi divided by 4. - */ - - -/** - * G_PRIVATE_INIT: - * @notify: a #GDestroyNotify - * - * A macro to assist with the static initialisation of a #GPrivate. - * - * This macro is useful for the case that a #GDestroyNotify function - * should be associated with the key. This is needed when the key will be - * used to point at memory that should be deallocated when the thread - * exits. - * - * Additionally, the #GDestroyNotify will also be called on the previous - * value stored in the key when g_private_replace() is used. - * - * If no #GDestroyNotify is needed, then use of this macro is not - * required -- if the #GPrivate is declared in static scope then it will - * be properly initialised by default (ie: to all zeros). See the - * examples below. - * - * |[ - * static GPrivate name_key = G_PRIVATE_INIT (g_free); - * - * // return value should not be freed - * const gchar * - * get_local_name (void) - * { - * return g_private_get (&name_key); - * } - * - * void - * set_local_name (const gchar *name) - * { - * g_private_replace (&name_key, g_strdup (name)); - * } - * - * - * static GPrivate count_key; // no free function - * - * gint - * get_local_count (void) - * { - * return GPOINTER_TO_INT (g_private_get (&count_key)); - * } - * - * void - * set_local_count (gint count) - * { - * g_private_set (&count_key, GINT_TO_POINTER (count)); - * } - * ]| - * - * Since: 2.32 - */ - - -/** - * G_SEARCHPATH_SEPARATOR: - * - * The search path separator character. - * This is ':' on UNIX machines and ';' under Windows. - */ - - -/** - * G_SEARCHPATH_SEPARATOR_S: - * - * The search path separator as a string. - * This is ":" on UNIX machines and ";" under Windows. - */ - - -/** - * G_SHELL_ERROR: - * - * Error domain for shell functions. - * - * Errors in this domain will be from the #GShellError enumeration. - * - * See #GError for information on error domains. - */ - - -/** - * G_SQRT2: - * - * The square root of two. - */ - - -/** - * G_STATIC_ASSERT: - * @expr: a constant expression - * - * The G_STATIC_ASSERT() macro lets the programmer check - * a condition at compile time, the condition needs to - * be compile time computable. The macro can be used in - * any place where a typedef is valid. - * - * A typedef is generally allowed in exactly the same places that - * a variable declaration is allowed. For this reason, you should - * not use G_STATIC_ASSERT() in the middle of blocks of code. - * - * The macro should only be used once per source code line. - * - * Since: 2.20 - */ - - -/** - * G_STATIC_ASSERT_EXPR: - * @expr: a constant expression - * - * The G_STATIC_ASSERT_EXPR() macro lets the programmer check - * a condition at compile time. The condition needs to be - * compile time computable. - * - * Unlike G_STATIC_ASSERT(), this macro evaluates to an expression - * and, as such, can be used in the middle of other expressions. - * Its value should be ignored. This can be accomplished by placing - * it as the first argument of a comma expression. - * - * |[ - * #define ADD_ONE_TO_INT(x) \ - * (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1)) - * ]| - * - * Since: 2.30 - */ - - -/** - * G_STMT_END: - * - * Used within multi-statement macros so that they can be used in places - * where only one statement is expected by the compiler. - */ - - -/** - * G_STMT_START: - * - * Used within multi-statement macros so that they can be used in places - * where only one statement is expected by the compiler. - */ - - -/** - * G_STRFUNC: - * - * Expands to a string identifying the current function. - * - * Since: 2.4 - */ - - -/** - * G_STRINGIFY: - * @macro_or_string: a macro or a string - * - * Accepts a macro or a string and converts it into a string after - * preprocessor argument expansion. For example, the following code: - * - * |[ - * #define AGE 27 - * const gchar *greeting = G_STRINGIFY (AGE) " today!"; - * ]| - * - * is transformed by the preprocessor into (code equivalent to): - * - * |[ - * const gchar *greeting = "27 today!"; - * ]| - */ - - -/** - * G_STRLOC: - * - * Expands to a string identifying the current code position. - */ - - -/** - * G_STRUCT_MEMBER: - * @member_type: the type of the struct field - * @struct_p: a pointer to a struct - * @struct_offset: the offset of the field from the start of the struct, - * in bytes - * - * Returns a member of a structure at a given offset, using the given type. - * - * Returns: the struct member - */ - - -/** - * G_STRUCT_MEMBER_P: - * @struct_p: a pointer to a struct - * @struct_offset: the offset from the start of the struct, in bytes - * - * Returns an untyped pointer to a given offset of a struct. - * - * Returns: an untyped pointer to @struct_p plus @struct_offset bytes - */ - - -/** - * G_STRUCT_OFFSET: - * @struct_type: a structure type, e.g. #GtkWidget - * @member: a field in the structure, e.g. @window - * - * Returns the offset, in bytes, of a member of a struct. - * - * Returns: the offset of @member from the start of @struct_type - */ - - -/** - * G_STR_DELIMITERS: - * - * The standard delimiters, used in g_strdelimit(). - */ - - -/** - * G_THREAD_ERROR: - * - * The error domain of the GLib thread subsystem. - */ - - -/** - * G_TRYLOCK: - * @name: the name of the lock - * - * Works like g_mutex_trylock(), but for a lock defined with - * %G_LOCK_DEFINE. - * - * Returns: %TRUE, if the lock could be locked. - */ - - -/** - * G_UNAVAILABLE: - * @maj: the major version that introduced the symbol - * @min: the minor version that introduced the symbol - * - * This macro can be used to mark a function declaration as unavailable. - * It must be placed before the function declaration. Use of a function - * that has been annotated with this macros will produce a compiler warning. - * - * Since: 2.32 - */ - - -/** - * G_UNLIKELY: - * @expr: the expression - * - * Hints the compiler that the expression is unlikely to evaluate to - * a true value. The compiler may use this information for optimizations. - * - * |[ - * if (G_UNLIKELY (random () == 1)) - * g_print ("a random one"); - * ]| - * - * Returns: the value of @expr - * Since: 2.2 - */ - - -/** - * G_UNLOCK: - * @name: the name of the lock - * - * Works like g_mutex_unlock(), but for a lock defined with - * %G_LOCK_DEFINE. - */ - - -/** - * G_USEC_PER_SEC: - * - * Number of microseconds in one second (1 million). - * This macro is provided for code readability. - */ - - -/** - * G_VARIANT_PARSE_ERROR: - * - * Error domain for GVariant text format parsing. Specific error codes - * are not currently defined for this domain. See #GError for - * information on error domains. - */ - - -/** - * G_VA_COPY: - * @ap1: the va_list variable to place a copy of @ap2 in - * @ap2: a va_list - * - * Portable way to copy va_list variables. - * - * In order to use this function, you must include string.h yourself, - * because this macro may use memmove() and GLib does not include - * string.h for you. - * - * Each invocation of `G_VA_COPY (ap1, ap2)` must be matched with a - * corresponding `va_end (ap1)` call in the same function. - */ - - -/** - * G_WIN32_DLLMAIN_FOR_DLL_NAME: - * @static: empty or "static" - * @dll_name: the name of the (pointer to the) char array where - * the DLL name will be stored. If this is used, you must also - * include `windows.h`. If you need a more complex DLL entry - * point function, you cannot use this - * - * On Windows, this macro defines a DllMain() function that stores - * the actual DLL name that the code being compiled will be included in. - * - * On non-Windows platforms, expands to nothing. - */ - - -/** - * G_WIN32_HAVE_WIDECHAR_API: - * - * On Windows, this macro defines an expression which evaluates to - * %TRUE if the code is running on a version of Windows where the wide - * character versions of the Win32 API functions, and the wide character - * versions of the C library functions work. (They are always present in - * the DLLs, but don't work on Windows 9x and Me.) - * - * On non-Windows platforms, it is not defined. - * - * Since: 2.6 - */ - - -/** - * G_WIN32_IS_NT_BASED: - * - * On Windows, this macro defines an expression which evaluates to - * %TRUE if the code is running on an NT-based Windows operating system. - * - * On non-Windows platforms, it is not defined. - * - * Since: 2.6 - */ - - -/** - * MAX: - * @a: a numeric value - * @b: a numeric value - * - * Calculates the maximum of @a and @b. - * - * Returns: the maximum of @a and @b. - */ - - -/** - * MAXPATHLEN: - * - * Provided for UNIX emulation on Windows; equivalent to UNIX - * macro %MAXPATHLEN, which is the maximum length of a filename - * (including full path). - */ - - -/** - * MIN: - * @a: a numeric value - * @b: a numeric value - * - * Calculates the minimum of @a and @b. - * - * Returns: the minimum of @a and @b. - */ - - -/** - * NC_: - * @Context: a message context, must be a string literal - * @String: a message id, must be a string literal - * - * Only marks a string for translation, with context. - * This is useful in situations where the translated strings can't - * be directly used, e.g. in string array initializers. To get the - * translated string, you should call g_dpgettext2() at runtime. - * - * |[ - * { - * static const char *messages[] = { - * NC_("some context", "some very meaningful message"), - * NC_("some context", "and another one") - * }; - * const char *string; - * ... - * string - * = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message") - * : g_dpgettext2 (NULL, "some context", messages[index]); - * - * fputs (string); - * ... - * } - * ]| - * - * If you are using the NC_() macro, you need to make sure that you pass - * `--keyword=NC_:1c,2` to xgettext when extracting messages. - * Note that this only works with GNU gettext >= 0.15. Intltool has support - * for the NC_() macro since version 0.40.1. - * - * Since: 2.18 - */ - - -/** - * NULL: - * - * Defines the standard %NULL pointer. - */ - - -/** - * N_: - * @String: the string to be translated - * - * Only marks a string for translation. This is useful in situations - * where the translated strings can't be directly used, e.g. in string - * array initializers. To get the translated string, call gettext() - * at runtime. - * |[ - * { - * static const char *messages[] = { - * N_("some very meaningful message"), - * N_("and another one") - * }; - * const char *string; - * ... - * string - * = index > 1 ? _("a default message") : gettext (messages[index]); - * - * fputs (string); - * ... - * } - * ]| - * - * Since: 2.4 - */ - - -/** - * Q_: - * @String: the string to be translated, with a '|'-separated prefix - * which must not be translated - * - * Like _(), but handles context in message ids. This has the advantage - * that the string can be adorned with a prefix to guarantee uniqueness - * and provide context to the translator. - * - * One use case given in the gettext manual is GUI translation, where one - * could e.g. disambiguate two "Open" menu entries as "File|Open" and - * "Printer|Open". Another use case is the string "Russian" which may - * have to be translated differently depending on whether it's the name - * of a character set or a language. This could be solved by using - * "charset|Russian" and "language|Russian". - * - * See the C_() macro for a different way to mark up translatable strings - * with context. - * - * If you are using the Q_() macro, you need to make sure that you pass - * `--keyword=Q_` to xgettext when extracting messages. - * If you are using GNU gettext >= 0.15, you can also use - * `--keyword=Q_:1g` to let xgettext split the context - * string off into a msgctxt line in the po file. - * - * Returns: the translated message - * Since: 2.4 - */ - - -/** - * SECTION:arcbox - * @Title: Atomically reference counted data - * @Short_description: Allocated memory with atomic reference counting semantics - * - * An "atomically reference counted box", or "ArcBox", is an opaque wrapper - * data type that is guaranteed to be as big as the size of a given data type, - * and which augments the given data type with thread safe reference counting - * semantics for its memory management. - * - * ArcBox is useful if you have a plain old data type, like a structure - * typically placed on the stack, and you wish to provide additional API - * to use it on the heap; or if you want to implement a new type to be - * passed around by reference without necessarily implementing copy/free - * semantics or your own reference counting. - * - * The typical use is: - * - * |[ - * typedef struct { - * char *name; - * char *address; - * char *city; - * char *state; - * int age; - * } Person; - * - * Person * - * person_new (void) - * { - * return g_atomic_rc_box_new0 (Person); - * } - * ]| - * - * Every time you wish to acquire a reference on the memory, you should - * call g_atomic_rc_box_acquire(); similarly, when you wish to release a reference - * you should call g_atomic_rc_box_release(): - * - * |[ - * // Add a Person to the Database; the Database acquires ownership - * // of the Person instance - * void - * add_person_to_database (Database *db, Person *p) - * { - * db->persons = g_list_prepend (db->persons, g_atomic_rc_box_acquire (p)); - * } - * - * // Removes a Person from the Database; the reference acquired by - * // add_person_to_database() is released here - * void - * remove_person_from_database (Database *db, Person *p) - * { - * db->persons = g_list_remove (db->persons, p); - * g_atomic_rc_box_release (p); - * } - * ]| - * - * If you have additional memory allocated inside the structure, you can - * use g_atomic_rc_box_release_full(), which takes a function pointer, which - * will be called if the reference released was the last: - * - * |[ - * void - * person_clear (Person *p) - * { - * g_free (p->name); - * g_free (p->address); - * g_free (p->city); - * g_free (p->state); - * } - * - * void - * remove_person_from_database (Database *db, Person *p) - * { - * db->persons = g_list_remove (db->persons, p); - * g_atomic_rc_box_release_full (p, (GDestroyNotify) person_clear); - * } - * ]| - * - * If you wish to transfer the ownership of a reference counted data - * type without increasing the reference count, you can use g_steal_pointer(): - * - * |[ - * Person *p = g_atomic_rc_box_new (Person); - * - * fill_person_details (p); - * - * add_person_to_database (db, g_steal_pointer (&p)); - * ]| - * - * ## Thread safety - * - * The reference counting operations on data allocated using g_atomic_rc_box_alloc(), - * g_atomic_rc_box_new(), and g_atomic_rc_box_dup() are guaranteed to be atomic, and thus - * can be safely be performed by different threads. It is important to note that - * only the reference acquisition and release are atomic; changes to the content - * of the data are your responsibility. - * - * ## Automatic pointer clean up - * - * If you want to add g_autoptr() support to your plain old data type through - * reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and - * g_atomic_rc_box_release(): - * - * |[ - * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_atomic_rc_box_release) - * ]| - * - * If you need to clear the contents of the data, you will need to use an - * ancillary function that calls g_rc_box_release_full(): - * - * |[ - * static void - * my_data_struct_release (MyDataStruct *data) - * { - * // my_data_struct_clear() is defined elsewhere - * g_atomic_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); - * } - * - * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release) - * ]| - * - * Since: 2.58 - */ - - -/** - * SECTION:arrays - * @title: Arrays - * @short_description: arrays of arbitrary elements which grow - * automatically as elements are added - * - * Arrays are similar to standard C arrays, except that they grow - * automatically as elements are added. - * - * Array elements can be of any size (though all elements of one array - * are the same size), and the array can be automatically cleared to - * '0's and zero-terminated. - * - * To create a new array use g_array_new(). - * - * To add elements to an array with a cost of O(n) at worst, use - * g_array_append_val(), g_array_append_vals(), g_array_prepend_val(), - * g_array_prepend_vals(), g_array_insert_val() and g_array_insert_vals(). - * - * To access an element of an array in O(1) (to read it or to write it), - * use g_array_index(). - * - * To set the size of an array, use g_array_set_size(). - * - * To free an array, use g_array_unref() or g_array_free(). - * - * All the sort functions are internally calling a quick-sort (or similar) - * function with an average cost of O(n log(n)) and a worst case - * cost of O(n^2). - * - * Here is an example that stores integers in a #GArray: - * |[ - * GArray *garray; - * gint i; - * // We create a new array to store gint values. - * // We don't want it zero-terminated or cleared to 0's. - * garray = g_array_new (FALSE, FALSE, sizeof (gint)); - * for (i = 0; i < 10000; i++) - * g_array_append_val (garray, i); - * for (i = 0; i < 10000; i++) - * if (g_array_index (garray, gint, i) != i) - * g_print ("ERROR: got %d instead of %d\n", - * g_array_index (garray, gint, i), i); - * g_array_free (garray, TRUE); - * ]| - */ - - -/** - * SECTION:arrays_byte - * @title: Byte Arrays - * @short_description: arrays of bytes - * - * #GByteArray is a mutable array of bytes based on #GArray, to provide arrays - * of bytes which grow automatically as elements are added. - * - * To create a new #GByteArray use g_byte_array_new(). To add elements to a - * #GByteArray, use g_byte_array_append(), and g_byte_array_prepend(). - * - * To set the size of a #GByteArray, use g_byte_array_set_size(). - * - * To free a #GByteArray, use g_byte_array_free(). - * - * An example for using a #GByteArray: - * |[ - * GByteArray *gbarray; - * gint i; - * - * gbarray = g_byte_array_new (); - * for (i = 0; i < 10000; i++) - * g_byte_array_append (gbarray, (guint8*) "abcd", 4); - * - * for (i = 0; i < 10000; i++) - * { - * g_assert (gbarray->data[4*i] == 'a'); - * g_assert (gbarray->data[4*i+1] == 'b'); - * g_assert (gbarray->data[4*i+2] == 'c'); - * g_assert (gbarray->data[4*i+3] == 'd'); - * } - * - * g_byte_array_free (gbarray, TRUE); - * ]| - * - * See #GBytes if you are interested in an immutable object representing a - * sequence of bytes. - */ - - -/** - * SECTION:arrays_pointer - * @title: Pointer Arrays - * @short_description: arrays of pointers to any type of data, which - * grow automatically as new elements are added - * - * Pointer Arrays are similar to Arrays but are used only for storing - * pointers. - * - * If you remove elements from the array, elements at the end of the - * array are moved into the space previously occupied by the removed - * element. This means that you should not rely on the index of particular - * elements remaining the same. You should also be careful when deleting - * elements while iterating over the array. - * - * To create a pointer array, use g_ptr_array_new(). - * - * To add elements to a pointer array, use g_ptr_array_add(). - * - * To remove elements from a pointer array, use g_ptr_array_remove(), - * g_ptr_array_remove_index() or g_ptr_array_remove_index_fast(). - * - * To access an element of a pointer array, use g_ptr_array_index(). - * - * To set the size of a pointer array, use g_ptr_array_set_size(). - * - * To free a pointer array, use g_ptr_array_free(). - * - * An example using a #GPtrArray: - * |[ - * GPtrArray *array; - * gchar *string1 = "one"; - * gchar *string2 = "two"; - * gchar *string3 = "three"; - * - * array = g_ptr_array_new (); - * g_ptr_array_add (array, (gpointer) string1); - * g_ptr_array_add (array, (gpointer) string2); - * g_ptr_array_add (array, (gpointer) string3); - * - * if (g_ptr_array_index (array, 0) != (gpointer) string1) - * g_print ("ERROR: got %p instead of %p\n", - * g_ptr_array_index (array, 0), string1); - * - * g_ptr_array_free (array, TRUE); - * ]| - */ - - -/** - * SECTION:async_queues - * @title: Asynchronous Queues - * @short_description: asynchronous communication between threads - * @see_also: #GThreadPool - * - * Often you need to communicate between different threads. In general - * it's safer not to do this by shared memory, but by explicit message - * passing. These messages only make sense asynchronously for - * multi-threaded applications though, as a synchronous operation could - * as well be done in the same thread. - * - * Asynchronous queues are an exception from most other GLib data - * structures, as they can be used simultaneously from multiple threads - * without explicit locking and they bring their own builtin reference - * counting. This is because the nature of an asynchronous queue is that - * it will always be used by at least 2 concurrent threads. - * - * For using an asynchronous queue you first have to create one with - * g_async_queue_new(). #GAsyncQueue structs are reference counted, - * use g_async_queue_ref() and g_async_queue_unref() to manage your - * references. - * - * A thread which wants to send a message to that queue simply calls - * g_async_queue_push() to push the message to the queue. - * - * A thread which is expecting messages from an asynchronous queue - * simply calls g_async_queue_pop() for that queue. If no message is - * available in the queue at that point, the thread is now put to sleep - * until a message arrives. The message will be removed from the queue - * and returned. The functions g_async_queue_try_pop() and - * g_async_queue_timeout_pop() can be used to only check for the presence - * of messages or to only wait a certain time for messages respectively. - * - * For almost every function there exist two variants, one that locks - * the queue and one that doesn't. That way you can hold the queue lock - * (acquire it with g_async_queue_lock() and release it with - * g_async_queue_unlock()) over multiple queue accessing instructions. - * This can be necessary to ensure the integrity of the queue, but should - * only be used when really necessary, as it can make your life harder - * if used unwisely. Normally you should only use the locking function - * variants (those without the _unlocked suffix). - * - * In many cases, it may be more convenient to use #GThreadPool when - * you need to distribute work to a set of worker threads instead of - * using #GAsyncQueue manually. #GThreadPool uses a GAsyncQueue - * internally. - */ - - -/** - * SECTION:atomic_operations - * @title: Atomic Operations - * @short_description: basic atomic integer and pointer operations - * @see_also: #GMutex - * - * The following is a collection of compiler macros to provide atomic - * access to integer and pointer-sized values. - * - * The macros that have 'int' in the name will operate on pointers to - * #gint and #guint. The macros with 'pointer' in the name will operate - * on pointers to any pointer-sized value, including #gsize. There is - * no support for 64bit operations on platforms with 32bit pointers - * because it is not generally possible to perform these operations - * atomically. - * - * The get, set and exchange operations for integers and pointers - * nominally operate on #gint and #gpointer, respectively. Of the - * arithmetic operations, the 'add' operation operates on (and returns) - * signed integer values (#gint and #gssize) and the 'and', 'or', and - * 'xor' operations operate on (and return) unsigned integer values - * (#guint and #gsize). - * - * All of the operations act as a full compiler and (where appropriate) - * hardware memory barrier. Acquire and release or producer and - * consumer barrier semantics are not available through this API. - * - * It is very important that all accesses to a particular integer or - * pointer be performed using only this API and that different sizes of - * operation are not mixed or used on overlapping memory regions. Never - * read or assign directly from or to a value -- always use this API. - * - * For simple reference counting purposes you should use - * g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that - * fall outside of simple reference counting patterns are prone to - * subtle bugs and occasionally undefined behaviour. It is also worth - * noting that since all of these operations require global - * synchronisation of the entire machine, they can be quite slow. In - * the case of performing multiple atomic operations it can often be - * faster to simply acquire a mutex lock around the critical area, - * perform the operations normally and then release the lock. - */ - - -/** - * SECTION:base64 - * @title: Base64 Encoding - * @short_description: encodes and decodes data in Base64 format - * - * Base64 is an encoding that allows a sequence of arbitrary bytes to be - * encoded as a sequence of printable ASCII characters. For the definition - * of Base64, see - * [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt) - * or - * [RFC 2045](http://www.ietf.org/rfc/rfc2045.txt). - * Base64 is most commonly used as a MIME transfer encoding - * for email. - * - * GLib supports incremental encoding using g_base64_encode_step() and - * g_base64_encode_close(). Incremental decoding can be done with - * g_base64_decode_step(). To encode or decode data in one go, use - * g_base64_encode() or g_base64_decode(). To avoid memory allocation when - * decoding, you can use g_base64_decode_inplace(). - * - * Support for Base64 encoding has been added in GLib 2.12. - */ - - -/** - * SECTION:bookmarkfile - * @title: Bookmark file parser - * @short_description: parses files containing bookmarks - * - * GBookmarkFile lets you parse, edit or create files containing bookmarks - * to URI, along with some meta-data about the resource pointed by the URI - * like its MIME type, the application that is registering the bookmark and - * the icon that should be used to represent the bookmark. The data is stored - * using the - * [Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec). - * - * The syntax of the bookmark files is described in detail inside the - * Desktop Bookmark Specification, here is a quick summary: bookmark - * files use a sub-class of the XML Bookmark Exchange Language - * specification, consisting of valid UTF-8 encoded XML, under the - * root element; each bookmark is stored inside a - * element, using its URI: no relative paths can - * be used inside a bookmark file. The bookmark may have a user defined - * title and description, to be used instead of the URI. Under the - * element, with its owner attribute set to - * `http://freedesktop.org`, is stored the meta-data about a resource - * pointed by its URI. The meta-data consists of the resource's MIME - * type; the applications that have registered a bookmark; the groups - * to which a bookmark belongs to; a visibility flag, used to set the - * bookmark as "private" to the applications and groups that has it - * registered; the URI and MIME type of an icon, to be used when - * displaying the bookmark inside a GUI. - * - * Here is an example of a bookmark file: - * [bookmarks.xbel](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/bookmarks.xbel) - * - * A bookmark file might contain more than one bookmark; each bookmark - * is accessed through its URI. - * - * The important caveat of bookmark files is that when you add a new - * bookmark you must also add the application that is registering it, using - * g_bookmark_file_add_application() or g_bookmark_file_set_application_info(). - * If a bookmark has no applications then it won't be dumped when creating - * the on disk representation, using g_bookmark_file_to_data() or - * g_bookmark_file_to_file(). - * - * The #GBookmarkFile parser was added in GLib 2.12. - */ - - -/** - * SECTION:byte_order - * @title: Byte Order Macros - * @short_description: a portable way to convert between different byte orders - * - * These macros provide a portable way to determine the host byte order - * and to convert values between different byte orders. - * - * The byte order is the order in which bytes are stored to create larger - * data types such as the #gint and #glong values. - * The host byte order is the byte order used on the current machine. - * - * Some processors store the most significant bytes (i.e. the bytes that - * hold the largest part of the value) first. These are known as big-endian - * processors. Other processors (notably the x86 family) store the most - * significant byte last. These are known as little-endian processors. - * - * Finally, to complicate matters, some other processors store the bytes in - * a rather curious order known as PDP-endian. For a 4-byte word, the 3rd - * most significant byte is stored first, then the 4th, then the 1st and - * finally the 2nd. - * - * Obviously there is a problem when these different processors communicate - * with each other, for example over networks or by using binary file formats. - * This is where these macros come in. They are typically used to convert - * values into a byte order which has been agreed on for use when - * communicating between different processors. The Internet uses what is - * known as 'network byte order' as the standard byte order (which is in - * fact the big-endian byte order). - * - * Note that the byte order conversion macros may evaluate their arguments - * multiple times, thus you should not use them with arguments which have - * side-effects. - */ - - -/** - * SECTION:checkedmath - * @title: Bounds-checking integer arithmetic - * @short_description: a set of helpers for performing checked integer arithmetic - * - * GLib offers a set of macros for doing additions and multiplications - * of unsigned integers, with checks for overflows. - * - * The helpers all have three arguments. A pointer to the destination - * is always the first argument and the operands to the operation are - * the other two. - * - * Following standard GLib convention, the helpers return %TRUE in case - * of success (ie: no overflow). - * - * The helpers may be macros, normal functions or inlines. They may be - * implemented with inline assembly or compiler intrinsics where - * available. - * - * Since: 2.48 - */ - - -/** - * SECTION:checksum - * @title: Data Checksums - * @short_description: computes the checksum for data - * - * GLib provides a generic API for computing checksums (or "digests") - * for a sequence of arbitrary bytes, using various hashing algorithms - * like MD5, SHA-1 and SHA-256. Checksums are commonly used in various - * environments and specifications. - * - * GLib supports incremental checksums using the GChecksum data - * structure, by calling g_checksum_update() as long as there's data - * available and then using g_checksum_get_string() or - * g_checksum_get_digest() to compute the checksum and return it either - * as a string in hexadecimal form, or as a raw sequence of bytes. To - * compute the checksum for binary blobs and NUL-terminated strings in - * one go, use the convenience functions g_compute_checksum_for_data() - * and g_compute_checksum_for_string(), respectively. - * - * Support for checksums has been added in GLib 2.16 - */ - - -/** - * SECTION:conversions - * @title: Character Set Conversion - * @short_description: convert strings between different character sets - * - * The g_convert() family of function wraps the functionality of iconv(). - * In addition to pure character set conversions, GLib has functions to - * deal with the extra complications of encodings for file names. - * - * ## File Name Encodings - * - * Historically, UNIX has not had a defined encoding for file names: - * a file name is valid as long as it does not have path separators - * in it ("/"). However, displaying file names may require conversion: - * from the character set in which they were created, to the character - * set in which the application operates. Consider the Spanish file name - * "Presentación.sxi". If the application which created it uses - * ISO-8859-1 for its encoding, - * |[ - * Character: P r e s e n t a c i ó n . s x i - * Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69 - * ]| - * However, if the application use UTF-8, the actual file name on - * disk would look like this: - * |[ - * Character: P r e s e n t a c i ó n . s x i - * Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69 - * ]| - * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use - * GLib do the same thing. If you get a file name from the file system, - * for example, from readdir() or from g_dir_read_name(), and you wish - * to display the file name to the user, you will need to convert it - * into UTF-8. The opposite case is when the user types the name of a - * file they wish to save: the toolkit will give you that string in - * UTF-8 encoding, and you will need to convert it to the character - * set used for file names before you can create the file with open() - * or fopen(). - * - * By default, GLib assumes that file names on disk are in UTF-8 - * encoding. This is a valid assumption for file systems which - * were created relatively recently: most applications use UTF-8 - * encoding for their strings, and that is also what they use for - * the file names they create. However, older file systems may - * still contain file names created in "older" encodings, such as - * ISO-8859-1. In this case, for compatibility reasons, you may want - * to instruct GLib to use that particular encoding for file names - * rather than UTF-8. You can do this by specifying the encoding for - * file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING] - * environment variable. For example, if your installation uses - * ISO-8859-1 for file names, you can put this in your `~/.profile`: - * |[ - * export G_FILENAME_ENCODING=ISO-8859-1 - * ]| - * GLib provides the functions g_filename_to_utf8() and - * g_filename_from_utf8() to perform the necessary conversions. - * These functions convert file names from the encoding specified - * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This - * [diagram][file-name-encodings-diagram] illustrates how - * these functions are used to convert between UTF-8 and the - * encoding for file names in the file system. - * - * ## Conversion between file name encodings # {#file-name-encodings-diagram) - * - * ![](file-name-encodings.png) - * - * ## Checklist for Application Writers - * - * This section is a practical summary of the detailed - * things to do to make sure your applications process file - * name encodings correctly. - * - * 1. If you get a file name from the file system from a function - * such as readdir() or gtk_file_chooser_get_filename(), you do - * not need to do any conversion to pass that file name to - * functions like open(), rename(), or fopen() -- those are "raw" - * file names which the file system understands. - * - * 2. If you need to display a file name, convert it to UTF-8 first - * by using g_filename_to_utf8(). If conversion fails, display a - * string like "Unknown file name". Do not convert this string back - * into the encoding used for file names if you wish to pass it to - * the file system; use the original file name instead. - * - * For example, the document window of a word processor could display - * "Unknown file name" in its title bar but still let the user save - * the file, as it would keep the raw file name internally. This - * can happen if the user has not set the `G_FILENAME_ENCODING` - * environment variable even though he has files whose names are - * not encoded in UTF-8. - * - * 3. If your user interface lets the user type a file name for saving - * or renaming, convert it to the encoding used for file names in - * the file system by using g_filename_from_utf8(). Pass the converted - * file name to functions like fopen(). If conversion fails, ask the - * user to enter a different file name. This can happen if the user - * types Japanese characters when `G_FILENAME_ENCODING` is set to - * `ISO-8859-1`, for example. - */ - - -/** - * SECTION:datalist - * @title: Keyed Data Lists - * @short_description: lists of data elements which are accessible by a - * string or GQuark identifier - * - * Keyed data lists provide lists of arbitrary data elements which can - * be accessed either with a string or with a #GQuark corresponding to - * the string. - * - * The #GQuark methods are quicker, since the strings have to be - * converted to #GQuarks anyway. - * - * Data lists are used for associating arbitrary data with #GObjects, - * using g_object_set_data() and related functions. - * - * To create a datalist, use g_datalist_init(). - * - * To add data elements to a datalist use g_datalist_id_set_data(), - * g_datalist_id_set_data_full(), g_datalist_set_data() and - * g_datalist_set_data_full(). - * - * To get data elements from a datalist use g_datalist_id_get_data() - * and g_datalist_get_data(). - * - * To iterate over all data elements in a datalist use - * g_datalist_foreach() (not thread-safe). - * - * To remove data elements from a datalist use - * g_datalist_id_remove_data() and g_datalist_remove_data(). - * - * To remove all data elements from a datalist, use g_datalist_clear(). - */ - - -/** - * SECTION:datasets - * @title: Datasets - * @short_description: associate groups of data elements with - * particular memory locations - * - * Datasets associate groups of data elements with particular memory - * locations. These are useful if you need to associate data with a - * structure returned from an external library. Since you cannot modify - * the structure, you use its location in memory as the key into a - * dataset, where you can associate any number of data elements with it. - * - * There are two forms of most of the dataset functions. The first form - * uses strings to identify the data elements associated with a - * location. The second form uses #GQuark identifiers, which are - * created with a call to g_quark_from_string() or - * g_quark_from_static_string(). The second form is quicker, since it - * does not require looking up the string in the hash table of #GQuark - * identifiers. - * - * There is no function to create a dataset. It is automatically - * created as soon as you add elements to it. - * - * To add data elements to a dataset use g_dataset_id_set_data(), - * g_dataset_id_set_data_full(), g_dataset_set_data() and - * g_dataset_set_data_full(). - * - * To get data elements from a dataset use g_dataset_id_get_data() and - * g_dataset_get_data(). - * - * To iterate over all data elements in a dataset use - * g_dataset_foreach() (not thread-safe). - * - * To remove data elements from a dataset use - * g_dataset_id_remove_data() and g_dataset_remove_data(). - * - * To destroy a dataset, use g_dataset_destroy(). - */ - - -/** - * SECTION:date - * @title: Date and Time Functions - * @short_description: calendrical calculations and miscellaneous time stuff - * - * The #GDate data structure represents a day between January 1, Year 1, - * and sometime a few thousand years in the future (right now it will go - * to the year 65535 or so, but g_date_set_parse() only parses up to the - * year 8000 or so - just count on "a few thousand"). #GDate is meant to - * represent everyday dates, not astronomical dates or historical dates - * or ISO timestamps or the like. It extrapolates the current Gregorian - * calendar forward and backward in time; there is no attempt to change - * the calendar to match time periods or locations. #GDate does not store - * time information; it represents a day. - * - * The #GDate implementation has several nice features; it is only a - * 64-bit struct, so storing large numbers of dates is very efficient. It - * can keep both a Julian and day-month-year representation of the date, - * since some calculations are much easier with one representation or the - * other. A Julian representation is simply a count of days since some - * fixed day in the past; for #GDate the fixed day is January 1, 1 AD. - * ("Julian" dates in the #GDate API aren't really Julian dates in the - * technical sense; technically, Julian dates count from the start of the - * Julian period, Jan 1, 4713 BC). - * - * #GDate is simple to use. First you need a "blank" date; you can get a - * dynamically allocated date from g_date_new(), or you can declare an - * automatic variable or array and initialize it by - * calling g_date_clear(). A cleared date is safe; it's safe to call - * g_date_set_dmy() and the other mutator functions to initialize the - * value of a cleared date. However, a cleared date is initially - * invalid, meaning that it doesn't represent a day that exists. - * It is undefined to call any of the date calculation routines on an - * invalid date. If you obtain a date from a user or other - * unpredictable source, you should check its validity with the - * g_date_valid() predicate. g_date_valid() is also used to check for - * errors with g_date_set_parse() and other functions that can - * fail. Dates can be invalidated by calling g_date_clear() again. - * - * It is very important to use the API to access the #GDate - * struct. Often only the day-month-year or only the Julian - * representation is valid. Sometimes neither is valid. Use the API. - * - * GLib also features #GDateTime which represents a precise time. - */ - - -/** - * SECTION:date-time - * @title: GDateTime - * @short_description: a structure representing Date and Time - * @see_also: #GTimeZone - * - * #GDateTime is a structure that combines a Gregorian date and time - * into a single structure. It provides many conversion and methods to - * manipulate dates and times. Time precision is provided down to - * microseconds and the time can range (proleptically) from 0001-01-01 - * 00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX - * time in the sense that it is oblivious to leap seconds. - * - * #GDateTime is an immutable object; once it has been created it cannot - * be modified further. All modifiers will create a new #GDateTime. - * Nearly all such functions can fail due to the date or time going out - * of range, in which case %NULL will be returned. - * - * #GDateTime is reference counted: the reference count is increased by calling - * g_date_time_ref() and decreased by calling g_date_time_unref(). When the - * reference count drops to 0, the resources allocated by the #GDateTime - * structure are released. - * - * Many parts of the API may produce non-obvious results. As an - * example, adding two months to January 31st will yield March 31st - * whereas adding one month and then one month again will yield either - * March 28th or March 29th. Also note that adding 24 hours is not - * always the same as adding one day (since days containing daylight - * savings time transitions are either 23 or 25 hours in length). - * - * #GDateTime is available since GLib 2.26. - */ - - -/** - * SECTION:error_reporting - * @Title: Error Reporting - * @Short_description: a system for reporting errors - * - * GLib provides a standard method of reporting errors from a called - * function to the calling code. (This is the same problem solved by - * exceptions in other languages.) It's important to understand that - * this method is both a data type (the #GError struct) and a [set of - * rules][gerror-rules]. If you use #GError incorrectly, then your code will not - * properly interoperate with other code that uses #GError, and users - * of your API will probably get confused. In most cases, [using #GError is - * preferred over numeric error codes][gerror-comparison], but there are - * situations where numeric error codes are useful for performance. - * - * First and foremost: #GError should only be used to report recoverable - * runtime errors, never to report programming errors. If the programmer - * has screwed up, then you should use g_warning(), g_return_if_fail(), - * g_assert(), g_error(), or some similar facility. (Incidentally, - * remember that the g_error() function should only be used for - * programming errors, it should not be used to print any error - * reportable via #GError.) - * - * Examples of recoverable runtime errors are "file not found" or - * "failed to parse input." Examples of programming errors are "NULL - * passed to strcmp()" or "attempted to free the same pointer twice." - * These two kinds of errors are fundamentally different: runtime errors - * should be handled or reported to the user, programming errors should - * be eliminated by fixing the bug in the program. This is why most - * functions in GLib and GTK+ do not use the #GError facility. - * - * Functions that can fail take a return location for a #GError as their - * last argument. On error, a new #GError instance will be allocated and - * returned to the caller via this argument. For example: - * |[ - * gboolean g_file_get_contents (const gchar *filename, - * gchar **contents, - * gsize *length, - * GError **error); - * ]| - * If you pass a non-%NULL value for the `error` argument, it should - * point to a location where an error can be placed. For example: - * |[ - * gchar *contents; - * GError *err = NULL; - * - * g_file_get_contents ("foo.txt", &contents, NULL, &err); - * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); - * if (err != NULL) - * { - * // Report error to user, and free error - * g_assert (contents == NULL); - * fprintf (stderr, "Unable to read file: %s\n", err->message); - * g_error_free (err); - * } - * else - * { - * // Use file contents - * g_assert (contents != NULL); - * } - * ]| - * Note that `err != NULL` in this example is a reliable indicator - * of whether g_file_get_contents() failed. Additionally, - * g_file_get_contents() returns a boolean which - * indicates whether it was successful. - * - * Because g_file_get_contents() returns %FALSE on failure, if you - * are only interested in whether it failed and don't need to display - * an error message, you can pass %NULL for the @error argument: - * |[ - * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors - * // no error occurred - * ; - * else - * // error - * ; - * ]| - * - * The #GError object contains three fields: @domain indicates the module - * the error-reporting function is located in, @code indicates the specific - * error that occurred, and @message is a user-readable error message with - * as many details as possible. Several functions are provided to deal - * with an error received from a called function: g_error_matches() - * returns %TRUE if the error matches a given domain and code, - * g_propagate_error() copies an error into an error location (so the - * calling function will receive it), and g_clear_error() clears an - * error location by freeing the error and resetting the location to - * %NULL. To display an error to the user, simply display the @message, - * perhaps along with additional context known only to the calling - * function (the file being opened, or whatever - though in the - * g_file_get_contents() case, the @message already contains a filename). - * - * Since error messages may be displayed to the user, they need to be valid - * UTF-8 (all GTK widgets expect text to be UTF-8). Keep this in mind in - * particular when formatting error messages with filenames, which are in - * the 'filename encoding', and need to be turned into UTF-8 using - * g_filename_to_utf8(), g_filename_display_name() or g_utf8_make_valid(). - * - * Note, however, that many error messages are too technical to display to the - * user in an application, so prefer to use g_error_matches() to categorize errors - * from called functions, and build an appropriate error message for the context - * within your application. Error messages from a #GError are more appropriate - * to be printed in system logs or on the command line. They are typically - * translated. - * - * When implementing a function that can report errors, the basic - * tool is g_set_error(). Typically, if a fatal error occurs you - * want to g_set_error(), then return immediately. g_set_error() - * does nothing if the error location passed to it is %NULL. - * Here's an example: - * |[ - * gint - * foo_open_file (GError **error) - * { - * gint fd; - * int saved_errno; - * - * g_return_val_if_fail (error == NULL || *error == NULL, -1); - * - * fd = open ("file.txt", O_RDONLY); - * saved_errno = errno; - * - * if (fd < 0) - * { - * g_set_error (error, - * FOO_ERROR, // error domain - * FOO_ERROR_BLAH, // error code - * "Failed to open file: %s", // error message format string - * g_strerror (saved_errno)); - * return -1; - * } - * else - * return fd; - * } - * ]| - * - * Things are somewhat more complicated if you yourself call another - * function that can report a #GError. If the sub-function indicates - * fatal errors in some way other than reporting a #GError, such as - * by returning %TRUE on success, you can simply do the following: - * |[ - * gboolean - * my_function_that_can_fail (GError **err) - * { - * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - * - * if (!sub_function_that_can_fail (err)) - * { - * // assert that error was set by the sub-function - * g_assert (err == NULL || *err != NULL); - * return FALSE; - * } - * - * // otherwise continue, no error occurred - * g_assert (err == NULL || *err == NULL); - * } - * ]| - * - * If the sub-function does not indicate errors other than by - * reporting a #GError (or if its return value does not reliably indicate - * errors) you need to create a temporary #GError - * since the passed-in one may be %NULL. g_propagate_error() is - * intended for use in this case. - * |[ - * gboolean - * my_function_that_can_fail (GError **err) - * { - * GError *tmp_error; - * - * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - * - * tmp_error = NULL; - * sub_function_that_can_fail (&tmp_error); - * - * if (tmp_error != NULL) - * { - * // store tmp_error in err, if err != NULL, - * // otherwise call g_error_free() on tmp_error - * g_propagate_error (err, tmp_error); - * return FALSE; - * } - * - * // otherwise continue, no error occurred - * } - * ]| - * - * Error pileups are always a bug. For example, this code is incorrect: - * |[ - * gboolean - * my_function_that_can_fail (GError **err) - * { - * GError *tmp_error; - * - * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - * - * tmp_error = NULL; - * sub_function_that_can_fail (&tmp_error); - * other_function_that_can_fail (&tmp_error); - * - * if (tmp_error != NULL) - * { - * g_propagate_error (err, tmp_error); - * return FALSE; - * } - * } - * ]| - * @tmp_error should be checked immediately after sub_function_that_can_fail(), - * and either cleared or propagated upward. The rule is: after each error, - * you must either handle the error, or return it to the calling function. - * - * Note that passing %NULL for the error location is the equivalent - * of handling an error by always doing nothing about it. So the - * following code is fine, assuming errors in sub_function_that_can_fail() - * are not fatal to my_function_that_can_fail(): - * |[ - * gboolean - * my_function_that_can_fail (GError **err) - * { - * GError *tmp_error; - * - * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - * - * sub_function_that_can_fail (NULL); // ignore errors - * - * tmp_error = NULL; - * other_function_that_can_fail (&tmp_error); - * - * if (tmp_error != NULL) - * { - * g_propagate_error (err, tmp_error); - * return FALSE; - * } - * } - * ]| - * - * Note that passing %NULL for the error location ignores errors; - * it's equivalent to - * `try { sub_function_that_can_fail (); } catch (...) {}` - * in C++. It does not mean to leave errors unhandled; it means - * to handle them by doing nothing. - * - * Error domains and codes are conventionally named as follows: - * - * - The error domain is called __ERROR, - * for example %G_SPAWN_ERROR or %G_THREAD_ERROR: - * |[ - * #define G_SPAWN_ERROR g_spawn_error_quark () - * - * G_DEFINE_QUARK (g-spawn-error-quark, g_spawn_error) - * ]| - * - * - The quark function for the error domain is called - * __error_quark, - * for example g_spawn_error_quark() or g_thread_error_quark(). - * - * - The error codes are in an enumeration called - * Error; - * for example, #GThreadError or #GSpawnError. - * - * - Members of the error code enumeration are called - * __ERROR_, - * for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN. - * - * - If there's a "generic" or "unknown" error code for unrecoverable - * errors it doesn't make sense to distinguish with specific codes, - * it should be called __ERROR_FAILED, - * for example %G_SPAWN_ERROR_FAILED. In the case of error code - * enumerations that may be extended in future releases, you should - * generally not handle this error code explicitly, but should - * instead treat any unrecognized error code as equivalent to - * FAILED. - * - * ## Comparison of #GError and traditional error handling # {#gerror-comparison} - * - * #GError has several advantages over traditional numeric error codes: - * importantly, tools like - * [gobject-introspection](https://developer.gnome.org/gi/stable/) understand - * #GErrors and convert them to exceptions in bindings; the message includes - * more information than just a code; and use of a domain helps prevent - * misinterpretation of error codes. - * - * #GError has disadvantages though: it requires a memory allocation, and - * formatting the error message string has a performance overhead. This makes it - * unsuitable for use in retry loops where errors are a common case, rather than - * being unusual. For example, using %G_IO_ERROR_WOULD_BLOCK means hitting these - * overheads in the normal control flow. String formatting overhead can be - * eliminated by using g_set_error_literal() in some cases. - * - * These performance issues can be compounded if a function wraps the #GErrors - * returned by the functions it calls: this multiplies the number of allocations - * and string formatting operations. This can be partially mitigated by using - * g_prefix_error(). - * - * ## Rules for use of #GError # {#gerror-rules} - * - * Summary of rules for use of #GError: - * - * - Do not report programming errors via #GError. - * - * - The last argument of a function that returns an error should - * be a location where a #GError can be placed (i.e. `GError **error`). - * If #GError is used with varargs, the `GError**` should be the last - * argument before the `...`. - * - * - The caller may pass %NULL for the `GError**` if they are not interested - * in details of the exact error that occurred. - * - * - If %NULL is passed for the `GError**` argument, then errors should - * not be returned to the caller, but your function should still - * abort and return if an error occurs. That is, control flow should - * not be affected by whether the caller wants to get a #GError. - * - * - If a #GError is reported, then your function by definition had a - * fatal failure and did not complete whatever it was supposed to do. - * If the failure was not fatal, then you handled it and you should not - * report it. If it was fatal, then you must report it and discontinue - * whatever you were doing immediately. - * - * - If a #GError is reported, out parameters are not guaranteed to - * be set to any defined value. - * - * - A `GError*` must be initialized to %NULL before passing its address - * to a function that can report errors. - * - * - #GError structs must not be stack-allocated. - * - * - "Piling up" errors is always a bug. That is, if you assign a - * new #GError to a `GError*` that is non-%NULL, thus overwriting - * the previous error, it indicates that you should have aborted - * the operation instead of continuing. If you were able to continue, - * you should have cleared the previous error with g_clear_error(). - * g_set_error() will complain if you pile up errors. - * - * - By convention, if you return a boolean value indicating success - * then %TRUE means success and %FALSE means failure. Avoid creating - * functions which have a boolean return value and a #GError parameter, - * but where the boolean does something other than signal whether the - * #GError is set. Among other problems, it requires C callers to allocate - * a temporary error. Instead, provide a `gboolean *` out parameter. - * There are functions in GLib itself such as g_key_file_has_key() that - * are hard to use because of this. If %FALSE is returned, the error must - * be set to a non-%NULL value. One exception to this is that in situations - * that are already considered to be undefined behaviour (such as when a - * g_return_val_if_fail() check fails), the error need not be set. - * Instead of checking separately whether the error is set, callers - * should ensure that they do not provoke undefined behaviour, then - * assume that the error will be set on failure. - * - * - A %NULL return value is also frequently used to mean that an error - * occurred. You should make clear in your documentation whether %NULL - * is a valid return value in non-error cases; if %NULL is a valid value, - * then users must check whether an error was returned to see if the - * function succeeded. - * - * - When implementing a function that can report errors, you may want - * to add a check at the top of your function that the error return - * location is either %NULL or contains a %NULL error (e.g. - * `g_return_if_fail (error == NULL || *error == NULL);`). - * - * ## Extended #GError Domains # {#gerror-extended-domains} - * - * Since GLib 2.68 it is possible to extend the #GError type. This is - * done with the G_DEFINE_EXTENDED_ERROR() macro. To create an - * extended #GError type do something like this in the header file: - * |[ - * typedef enum - * { - * MY_ERROR_BAD_REQUEST, - * } MyError; - * #define MY_ERROR (my_error_quark ()) - * GQuark my_error_quark (void); - * int - * my_error_get_parse_error_id (GError *error); - * const char * - * my_error_get_bad_request_details (GError *error); - * ]| - * and in implementation: - * |[ - * typedef struct - * { - * int parse_error_id; - * char *bad_request_details; - * } MyErrorPrivate; - * - * static void - * my_error_private_init (MyErrorPrivate *priv) - * { - * priv->parse_error_id = -1; - * // No need to set priv->bad_request_details to NULL, - * // the struct is initialized with zeros. - * } - * - * static void - * my_error_private_copy (const MyErrorPrivate *src_priv, MyErrorPrivate *dest_priv) - * { - * dest_priv->parse_error_id = src_priv->parse_error_id; - * dest_priv->bad_request_details = g_strdup (src_priv->bad_request_details); - * } - * - * static void - * my_error_private_clear (MyErrorPrivate *priv) - * { - * g_free (priv->bad_request_details); - * } - * - * // This defines the my_error_get_private and my_error_quark functions. - * G_DEFINE_EXTENDED_ERROR (MyError, my_error) - * - * int - * my_error_get_parse_error_id (GError *error) - * { - * MyErrorPrivate *priv = my_error_get_private (error); - * g_return_val_if_fail (priv != NULL, -1); - * return priv->parse_error_id; - * } - * - * const char * - * my_error_get_bad_request_details (GError *error) - * { - * MyErrorPrivate *priv = my_error_get_private (error); - * g_return_val_if_fail (priv != NULL, NULL); - * g_return_val_if_fail (error->code != MY_ERROR_BAD_REQUEST, NULL); - * return priv->bad_request_details; - * } - * - * static void - * my_error_set_bad_request (GError **error, - * const char *reason, - * int error_id, - * const char *details) - * { - * MyErrorPrivate *priv; - * g_set_error (error, MY_ERROR, MY_ERROR_BAD_REQUEST, "Invalid request: %s", reason); - * if (error != NULL && *error != NULL) - * { - * priv = my_error_get_private (error); - * g_return_val_if_fail (priv != NULL, NULL); - * priv->parse_error_id = error_id; - * priv->bad_request_details = g_strdup (details); - * } - * } - * ]| - * An example of use of the error could be: - * |[ - * gboolean - * send_request (GBytes *request, GError **error) - * { - * ParseFailedStatus *failure = validate_request (request); - * if (failure != NULL) - * { - * my_error_set_bad_request (error, failure->reason, failure->error_id, failure->details); - * parse_failed_status_free (failure); - * return FALSE; - * } - * - * return send_one (request, error); - * } - * ]| - * - * Please note that if you are a library author and your library - * exposes an existing error domain, then you can't make this error - * domain an extended one without breaking ABI. This is because - * earlier it was possible to create an error with this error domain - * on the stack and then copy it with g_error_copy(). If the new - * version of your library makes the error domain an extended one, - * then g_error_copy() called by code that allocated the error on the - * stack will try to copy more data than it used to, which will lead - * to undefined behavior. You must not stack-allocate errors with an - * extended error domain, and it is bad practice to stack-allocate any - * other #GErrors. - * - * Extended error domains in unloadable plugins/modules are not - * supported. - */ - - -/** - * SECTION:fileutils - * @title: File Utilities - * @short_description: various file-related functions - * - * Do not use these APIs unless you are porting a POSIX application to Windows. - * A more high-level file access API is provided as GIO — see the documentation - * for #GFile. - * - * There is a group of functions which wrap the common POSIX functions - * dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(), - * g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these - * wrappers is to make it possible to handle file names with any Unicode - * characters in them on Windows without having to use ifdefs and the - * wide character API in the application code. - * - * On some Unix systems, these APIs may be defined as identical to their POSIX - * counterparts. For this reason, you must check for and include the necessary - * header files (such as `fcntl.h`) before using functions like g_creat(). You - * must also define the relevant feature test macros. - * - * The pathname argument should be in the GLib file name encoding. - * On POSIX this is the actual on-disk encoding which might correspond - * to the locale settings of the process (or the `G_FILENAME_ENCODING` - * environment variable), or not. - * - * On Windows the GLib file name encoding is UTF-8. Note that the - * Microsoft C library does not use UTF-8, but has separate APIs for - * current system code page and wide characters (UTF-16). The GLib - * wrappers call the wide character API if present (on modern Windows - * systems), otherwise convert to/from the system code page. - * - * Another group of functions allows to open and read directories - * in the GLib file name encoding. These are g_dir_open(), - * g_dir_read_name(), g_dir_rewind(), g_dir_close(). - */ - - -/** - * SECTION:ghostutils - * @short_description: Internet hostname utilities - * - * Functions for manipulating internet hostnames; in particular, for - * converting between Unicode and ASCII-encoded forms of - * Internationalized Domain Names (IDNs). - * - * The - * [Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt) - * standards allow for the use - * of Unicode domain names in applications, while providing - * backward-compatibility with the old ASCII-only DNS, by defining an - * ASCII-Compatible Encoding of any given Unicode name, which can be - * used with non-IDN-aware applications and protocols. (For example, - * "Παν語.org" maps to "xn--4wa8awb4637h.org".) - */ - - -/** - * SECTION:gregex - * @title: Perl-compatible regular expressions - * @short_description: matches strings against regular expressions - * @see_also: [Regular expression syntax][glib-regex-syntax] - * - * The g_regex_*() functions implement regular - * expression pattern matching using syntax and semantics similar to - * Perl regular expression. - * - * Some functions accept a @start_position argument, setting it differs - * from just passing over a shortened string and setting #G_REGEX_MATCH_NOTBOL - * in the case of a pattern that begins with any kind of lookbehind assertion. - * For example, consider the pattern "\Biss\B" which finds occurrences of "iss" - * in the middle of words. ("\B" matches only if the current position in the - * subject is not a word boundary.) When applied to the string "Mississipi" - * from the fourth byte, namely "issipi", it does not match, because "\B" is - * always false at the start of the subject, which is deemed to be a word - * boundary. However, if the entire string is passed , but with - * @start_position set to 4, it finds the second occurrence of "iss" because - * it is able to look behind the starting point to discover that it is - * preceded by a letter. - * - * Note that, unless you set the #G_REGEX_RAW flag, all the strings passed - * to these functions must be encoded in UTF-8. The lengths and the positions - * inside the strings are in bytes and not in characters, so, for instance, - * "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a - * single character. If you set #G_REGEX_RAW the strings can be non-valid - * UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two - * bytes and two characters long. - * - * When matching a pattern, "\n" matches only against a "\n" character in - * the string, and "\r" matches only a "\r" character. To match any newline - * sequence use "\R". This particular group matches either the two-character - * sequence CR + LF ("\r\n"), or one of the single characters LF (linefeed, - * U+000A, "\n"), VT vertical tab, U+000B, "\v"), FF (formfeed, U+000C, "\f"), - * CR (carriage return, U+000D, "\r"), NEL (next line, U+0085), LS (line - * separator, U+2028), or PS (paragraph separator, U+2029). - * - * The behaviour of the dot, circumflex, and dollar metacharacters are - * affected by newline characters, the default is to recognize any newline - * character (the same characters recognized by "\R"). This can be changed - * with #G_REGEX_NEWLINE_CR, #G_REGEX_NEWLINE_LF and #G_REGEX_NEWLINE_CRLF - * compile options, and with #G_REGEX_MATCH_NEWLINE_ANY, - * #G_REGEX_MATCH_NEWLINE_CR, #G_REGEX_MATCH_NEWLINE_LF and - * #G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also - * relevant when compiling a pattern if #G_REGEX_EXTENDED is set, and an - * unescaped "#" outside a character class is encountered. This indicates - * a comment that lasts until after the next newline. - * - * When setting the %G_REGEX_JAVASCRIPT_COMPAT flag, pattern syntax and pattern - * matching is changed to be compatible with the way that regular expressions - * work in JavaScript. More precisely, a lonely ']' character in the pattern - * is a syntax error; the '\x' escape only allows 0 to 2 hexadecimal digits, and - * you must use the '\u' escape sequence with 4 hex digits to specify a unicode - * codepoint instead of '\x' or 'x{....}'. If '\x' or '\u' are not followed by - * the specified number of hex digits, they match 'x' and 'u' literally; also - * '\U' always matches 'U' instead of being an error in the pattern. Finally, - * pattern matching is modified so that back references to an unset subpattern - * group produces a match with the empty string instead of an error. See - * pcreapi(3) for more information. - * - * Creating and manipulating the same #GRegex structure from different - * threads is not a problem as #GRegex does not modify its internal - * state between creation and destruction, on the other hand #GMatchInfo - * is not threadsafe. - * - * The regular expressions low-level functionalities are obtained through - * the excellent - * [PCRE](http://www.pcre.org/) - * library written by Philip Hazel. - */ - - -/** - * SECTION:gstrvbuilder - * @title: GStrvBuilder - * @short_description: Helper to create NULL-terminated string arrays. - * - * #GStrvBuilder is a method of easily building dynamically sized - * NULL-terminated string arrays. - * - * The following example shows how to build a two element array: - * - * |[ - * g_autoptr(GStrvBuilder) builder = g_strv_builder_new (); - * g_strv_builder_add (builder, "hello"); - * g_strv_builder_add (builder, "world"); - * g_auto(GStrv) array = g_strv_builder_end (builder); - * ]| - * - * Since: 2.68 - */ - - -/** - * SECTION:gunix - * @title: UNIX-specific utilities and integration - * @short_description: pipes, signal handling - * @include: glib-unix.h - * - * Most of GLib is intended to be portable; in contrast, this set of - * functions is designed for programs which explicitly target UNIX, - * or are using it to build higher level abstractions which would be - * conditionally compiled if the platform matches G_OS_UNIX. - * - * To use these functions, you must explicitly include the - * "glib-unix.h" header. - */ - - -/** - * SECTION:guri - * @short_description: URI-handling utilities - * @include: glib.h - * - * The #GUri type and related functions can be used to parse URIs into - * their components, and build valid URIs from individual components. - * - * Note that #GUri scope is to help manipulate URIs in various applications, - * following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular, - * it doesn't intend to cover web browser needs, and doesn't implement the - * [WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to - * help prevent - * [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so - * #GUri is not suitable for formatting URIs for display to the user for making - * security-sensitive decisions. - * - * ## Relative and absolute URIs # {#relative-absolute-uris} - * - * As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the - * hierarchical nature of URIs means that they can either be ‘relative - * references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for - * clarity, ‘URIs’ are referred to in this documentation as - * ‘absolute URIs’ — although - * [in constrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3), - * fragment identifiers are always allowed). - * - * Relative references have one or more components of the URI missing. In - * particular, they have no scheme. Any other component, such as hostname, - * query, etc. may be missing, apart from a path, which has to be specified (but - * may be empty). The path may be relative, starting with `./` rather than `/`. - * - * For example, a valid relative reference is `./path?query`, - * `/?query#fragment` or `//example.com`. - * - * Absolute URIs have a scheme specified. Any other components of the URI which - * are missing are specified as explicitly unset in the URI, rather than being - * resolved relative to a base URI using g_uri_parse_relative(). - * - * For example, a valid absolute URI is `file:///home/bob` or - * `https://search.com?query=string`. - * - * A #GUri instance is always an absolute URI. A string may be an absolute URI - * or a relative reference; see the documentation for individual functions as to - * what forms they accept. - * - * ## Parsing URIs - * - * The most minimalist APIs for parsing URIs are g_uri_split() and - * g_uri_split_with_user(). These split a URI into its component - * parts, and return the parts; the difference between the two is that - * g_uri_split() treats the ‘userinfo’ component of the URI as a - * single element, while g_uri_split_with_user() can (depending on the - * #GUriFlags you pass) treat it as containing a username, password, - * and authentication parameters. Alternatively, g_uri_split_network() - * can be used when you are only interested in the components that are - * needed to initiate a network connection to the service (scheme, - * host, and port). - * - * g_uri_parse() is similar to g_uri_split(), but instead of returning - * individual strings, it returns a #GUri structure (and it requires - * that the URI be an absolute URI). - * - * g_uri_resolve_relative() and g_uri_parse_relative() allow you to - * resolve a relative URI relative to a base URI. - * g_uri_resolve_relative() takes two strings and returns a string, - * and g_uri_parse_relative() takes a #GUri and a string and returns a - * #GUri. - * - * All of the parsing functions take a #GUriFlags argument describing - * exactly how to parse the URI; see the documentation for that type - * for more details on the specific flags that you can pass. If you - * need to choose different flags based on the type of URI, you can - * use g_uri_peek_scheme() on the URI string to check the scheme - * first, and use that to decide what flags to parse it with. - * - * For example, you might want to use %G_URI_PARAMS_WWW_FORM when parsing the - * params for a web URI, so compare the result of g_uri_peek_scheme() against - * `http` and `https`. - * - * ## Building URIs - * - * g_uri_join() and g_uri_join_with_user() can be used to construct - * valid URI strings from a set of component strings. They are the - * inverse of g_uri_split() and g_uri_split_with_user(). - * - * Similarly, g_uri_build() and g_uri_build_with_user() can be used to - * construct a #GUri from a set of component strings. - * - * As with the parsing functions, the building functions take a - * #GUriFlags argument. In particular, it is important to keep in mind - * whether the URI components you are using are already `%`-encoded. If so, - * you must pass the %G_URI_FLAGS_ENCODED flag. - * - * ## `file://` URIs - * - * Note that Windows and Unix both define special rules for parsing - * `file://` URIs (involving non-UTF-8 character sets on Unix, and the - * interpretation of path separators on Windows). #GUri does not - * implement these rules. Use g_filename_from_uri() and - * g_filename_to_uri() if you want to properly convert between - * `file://` URIs and local filenames. - * - * ## URI Equality - * - * Note that there is no `g_uri_equal ()` function, because comparing - * URIs usefully requires scheme-specific knowledge that #GUri does - * not have. #GUri can help with normalization if you use the various - * encoded #GUriFlags as well as %G_URI_FLAGS_SCHEME_NORMALIZE however - * it is not comprehensive. - * For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same - * thing according to the `data:` URI specification which GLib does not - * handle. - * - * Since: 2.66 - */ - - -/** - * SECTION:gvariant - * @title: GVariant - * @short_description: strongly typed value datatype - * @see_also: GVariantType - * - * #GVariant is a variant datatype; it can contain one or more values - * along with information about the type of the values. - * - * A #GVariant may contain simple types, like an integer, or a boolean value; - * or complex types, like an array of two strings, or a dictionary of key - * value pairs. A #GVariant is also immutable: once it's been created neither - * its type nor its content can be modified further. - * - * GVariant is useful whenever data needs to be serialized, for example when - * sending method parameters in D-Bus, or when saving settings using GSettings. - * - * When creating a new #GVariant, you pass the data you want to store in it - * along with a string representing the type of data you wish to pass to it. - * - * For instance, if you want to create a #GVariant holding an integer value you - * can use: - * - * |[ - * GVariant *v = g_variant_new ("u", 40); - * ]| - * - * The string "u" in the first argument tells #GVariant that the data passed to - * the constructor (40) is going to be an unsigned integer. - * - * More advanced examples of #GVariant in use can be found in documentation for - * [GVariant format strings][gvariant-format-strings-pointers]. - * - * The range of possible values is determined by the type. - * - * The type system used by #GVariant is #GVariantType. - * - * #GVariant instances always have a type and a value (which are given - * at construction time). The type and value of a #GVariant instance - * can never change other than by the #GVariant itself being - * destroyed. A #GVariant cannot contain a pointer. - * - * #GVariant is reference counted using g_variant_ref() and - * g_variant_unref(). #GVariant also has floating reference counts -- - * see g_variant_ref_sink(). - * - * #GVariant is completely threadsafe. A #GVariant instance can be - * concurrently accessed in any way from any number of threads without - * problems. - * - * #GVariant is heavily optimised for dealing with data in serialized - * form. It works particularly well with data located in memory-mapped - * files. It can perform nearly all deserialization operations in a - * small constant time, usually touching only a single memory page. - * Serialized #GVariant data can also be sent over the network. - * - * #GVariant is largely compatible with D-Bus. Almost all types of - * #GVariant instances can be sent over D-Bus. See #GVariantType for - * exceptions. (However, #GVariant's serialization format is not the same - * as the serialization format of a D-Bus message body: use #GDBusMessage, - * in the gio library, for those.) - * - * For space-efficiency, the #GVariant serialization format does not - * automatically include the variant's length, type or endianness, - * which must either be implied from context (such as knowledge that a - * particular file format always contains a little-endian - * %G_VARIANT_TYPE_VARIANT which occupies the whole length of the file) - * or supplied out-of-band (for instance, a length, type and/or endianness - * indicator could be placed at the beginning of a file, network message - * or network stream). - * - * A #GVariant's size is limited mainly by any lower level operating - * system constraints, such as the number of bits in #gsize. For - * example, it is reasonable to have a 2GB file mapped into memory - * with #GMappedFile, and call g_variant_new_from_data() on it. - * - * For convenience to C programmers, #GVariant features powerful - * varargs-based value construction and destruction. This feature is - * designed to be embedded in other libraries. - * - * There is a Python-inspired text language for describing #GVariant - * values. #GVariant includes a printer for this language and a parser - * with type inferencing. - * - * ## Memory Use - * - * #GVariant tries to be quite efficient with respect to memory use. - * This section gives a rough idea of how much memory is used by the - * current implementation. The information here is subject to change - * in the future. - * - * The memory allocated by #GVariant can be grouped into 4 broad - * purposes: memory for serialized data, memory for the type - * information cache, buffer management memory and memory for the - * #GVariant structure itself. - * - * ## Serialized Data Memory - * - * This is the memory that is used for storing GVariant data in - * serialized form. This is what would be sent over the network or - * what would end up on disk, not counting any indicator of the - * endianness, or of the length or type of the top-level variant. - * - * The amount of memory required to store a boolean is 1 byte. 16, - * 32 and 64 bit integers and double precision floating point numbers - * use their "natural" size. Strings (including object path and - * signature strings) are stored with a nul terminator, and as such - * use the length of the string plus 1 byte. - * - * Maybe types use no space at all to represent the null value and - * use the same amount of space (sometimes plus one byte) as the - * equivalent non-maybe-typed value to represent the non-null case. - * - * Arrays use the amount of space required to store each of their - * members, concatenated. Additionally, if the items stored in an - * array are not of a fixed-size (ie: strings, other arrays, etc) - * then an additional framing offset is stored for each item. The - * size of this offset is either 1, 2 or 4 bytes depending on the - * overall size of the container. Additionally, extra padding bytes - * are added as required for alignment of child values. - * - * Tuples (including dictionary entries) use the amount of space - * required to store each of their members, concatenated, plus one - * framing offset (as per arrays) for each non-fixed-sized item in - * the tuple, except for the last one. Additionally, extra padding - * bytes are added as required for alignment of child values. - * - * Variants use the same amount of space as the item inside of the - * variant, plus 1 byte, plus the length of the type string for the - * item inside the variant. - * - * As an example, consider a dictionary mapping strings to variants. - * In the case that the dictionary is empty, 0 bytes are required for - * the serialization. - * - * If we add an item "width" that maps to the int32 value of 500 then - * we will use 4 byte to store the int32 (so 6 for the variant - * containing it) and 6 bytes for the string. The variant must be - * aligned to 8 after the 6 bytes of the string, so that's 2 extra - * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used - * for the dictionary entry. An additional 1 byte is added to the - * array as a framing offset making a total of 15 bytes. - * - * If we add another entry, "title" that maps to a nullable string - * that happens to have a value of null, then we use 0 bytes for the - * null value (and 3 bytes for the variant to contain it along with - * its type string) plus 6 bytes for the string. Again, we need 2 - * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. - * - * We now require extra padding between the two items in the array. - * After the 14 bytes of the first item, that's 2 bytes required. - * We now require 2 framing offsets for an extra two - * bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item - * dictionary. - * - * ## Type Information Cache - * - * For each GVariant type that currently exists in the program a type - * information structure is kept in the type information cache. The - * type information structure is required for rapid deserialization. - * - * Continuing with the above example, if a #GVariant exists with the - * type "a{sv}" then a type information struct will exist for - * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type - * will share the same type information. Additionally, all - * single-digit types are stored in read-only static memory and do - * not contribute to the writable memory footprint of a program using - * #GVariant. - * - * Aside from the type information structures stored in read-only - * memory, there are two forms of type information. One is used for - * container types where there is a single element type: arrays and - * maybe types. The other is used for container types where there - * are multiple element types: tuples and dictionary entries. - * - * Array type info structures are 6 * sizeof (void *), plus the - * memory required to store the type string itself. This means that - * on 32-bit systems, the cache entry for "a{sv}" would require 30 - * bytes of memory (plus malloc overhead). - * - * Tuple type info structures are 6 * sizeof (void *), plus 4 * - * sizeof (void *) for each item in the tuple, plus the memory - * required to store the type string itself. A 2-item tuple, for - * example, would have a type information structure that consumed - * writable memory in the size of 14 * sizeof (void *) (plus type - * string) This means that on 32-bit systems, the cache entry for - * "{sv}" would require 61 bytes of memory (plus malloc overhead). - * - * This means that in total, for our "a{sv}" example, 91 bytes of - * type information would be allocated. - * - * The type information cache, additionally, uses a #GHashTable to - * store and look up the cached items and stores a pointer to this - * hash table in static storage. The hash table is freed when there - * are zero items in the type cache. - * - * Although these sizes may seem large it is important to remember - * that a program will probably only have a very small number of - * different types of values in it and that only one type information - * structure is required for many different values of the same type. - * - * ## Buffer Management Memory - * - * #GVariant uses an internal buffer management structure to deal - * with the various different possible sources of serialized data - * that it uses. The buffer is responsible for ensuring that the - * correct call is made when the data is no longer in use by - * #GVariant. This may involve a g_free() or a g_slice_free() or - * even g_mapped_file_unref(). - * - * One buffer management structure is used for each chunk of - * serialized data. The size of the buffer management structure - * is 4 * (void *). On 32-bit systems, that's 16 bytes. - * - * ## GVariant structure - * - * The size of a #GVariant structure is 6 * (void *). On 32-bit - * systems, that's 24 bytes. - * - * #GVariant structures only exist if they are explicitly created - * with API calls. For example, if a #GVariant is constructed out of - * serialized data for the example given above (with the dictionary) - * then although there are 9 individual values that comprise the - * entire dictionary (two keys, two values, two variants containing - * the values, two dictionary entries, plus the dictionary itself), - * only 1 #GVariant instance exists -- the one referring to the - * dictionary. - * - * If calls are made to start accessing the other values then - * #GVariant instances will exist for those values only for as long - * as they are in use (ie: until you call g_variant_unref()). The - * type information is shared. The serialized data and the buffer - * management structure for that serialized data is shared by the - * child. - * - * ## Summary - * - * To put the entire example together, for our dictionary mapping - * strings to variants (with two entries, as given above), we are - * using 91 bytes of memory for type information, 29 bytes of memory - * for the serialized data, 16 bytes for buffer management and 24 - * bytes for the #GVariant instance, or a total of 160 bytes, plus - * malloc overhead. If we were to use g_variant_get_child_value() to - * access the two dictionary entries, we would use an additional 48 - * bytes. If we were to have other dictionaries of the same type, we - * would use more memory for the serialized data and buffer - * management for those dictionaries, but the type information would - * be shared. - */ - - -/** - * SECTION:gvarianttype - * @title: GVariantType - * @short_description: introduction to the GVariant type system - * @see_also: #GVariantType, #GVariant - * - * This section introduces the GVariant type system. It is based, in - * large part, on the D-Bus type system, with two major changes and - * some minor lifting of restrictions. The - * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html), - * therefore, provides a significant amount of - * information that is useful when working with GVariant. - * - * The first major change with respect to the D-Bus type system is the - * introduction of maybe (or "nullable") types. Any type in GVariant can be - * converted to a maybe type, in which case, "nothing" (or "null") becomes a - * valid value. Maybe types have been added by introducing the - * character "m" to type strings. - * - * The second major change is that the GVariant type system supports the - * concept of "indefinite types" -- types that are less specific than - * the normal types found in D-Bus. For example, it is possible to speak - * of "an array of any type" in GVariant, where the D-Bus type system - * would require you to speak of "an array of integers" or "an array of - * strings". Indefinite types have been added by introducing the - * characters "*", "?" and "r" to type strings. - * - * Finally, all arbitrary restrictions relating to the complexity of - * types are lifted along with the restriction that dictionary entries - * may only appear nested inside of arrays. - * - * Just as in D-Bus, GVariant types are described with strings ("type - * strings"). Subject to the differences mentioned above, these strings - * are of the same form as those found in D-Bus. Note, however: D-Bus - * always works in terms of messages and therefore individual type - * strings appear nowhere in its interface. Instead, "signatures" - * are a concatenation of the strings of the type of each argument in a - * message. GVariant deals with single values directly so GVariant type - * strings always describe the type of exactly one value. This means - * that a D-Bus signature string is generally not a valid GVariant type - * string -- except in the case that it is the signature of a message - * containing exactly one argument. - * - * An indefinite type is similar in spirit to what may be called an - * abstract type in other type systems. No value can exist that has an - * indefinite type as its type, but values can exist that have types - * that are subtypes of indefinite types. That is to say, - * g_variant_get_type() will never return an indefinite type, but - * calling g_variant_is_of_type() with an indefinite type may return - * %TRUE. For example, you cannot have a value that represents "an - * array of no particular type", but you can have an "array of integers" - * which certainly matches the type of "an array of no particular type", - * since "array of integers" is a subtype of "array of no particular - * type". - * - * This is similar to how instances of abstract classes may not - * directly exist in other type systems, but instances of their - * non-abstract subtypes may. For example, in GTK, no object that has - * the type of #GtkBin can exist (since #GtkBin is an abstract class), - * but a #GtkWindow can certainly be instantiated, and you would say - * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of - * #GtkBin). - * - * ## GVariant Type Strings - * - * A GVariant type string can be any of the following: - * - * - any basic type string (listed below) - * - * - "v", "r" or "*" - * - * - one of the characters 'a' or 'm', followed by another type string - * - * - the character '(', followed by a concatenation of zero or more other - * type strings, followed by the character ')' - * - * - the character '{', followed by a basic type string (see below), - * followed by another type string, followed by the character '}' - * - * A basic type string describes a basic type (as per - * g_variant_type_is_basic()) and is always a single character in length. - * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t", - * "h", "d", "s", "o", "g" and "?". - * - * The above definition is recursive to arbitrary depth. "aaaaai" and - * "(ui(nq((y)))s)" are both valid type strings, as is - * "a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant - * imposes a limit on recursion depth of 65 nested containers. This is the - * limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to - * be nested in a top-level tuple. - * - * The meaning of each of the characters is as follows: - * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. - * - `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte. - * - `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer. - * - `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer. - * - `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer. - * - `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer. - * - `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer. - * - `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer. - * - `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value - * that, by convention, is used as an index into an array of file - * descriptors that are sent alongside a D-Bus message. - * - `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision - * floating point value. - * - `s`: the type string of %G_VARIANT_TYPE_STRING; a string. - * - `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form - * of a D-Bus object path. - * - `g`: the type string of %G_VARIANT_TYPE_SIGNATURE; a string in the form of - * a D-Bus type signature. - * - `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that - * is a supertype of any of the basic types. - * - `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that - * contain any other type of value. - * - `a`: used as a prefix on another type string to mean an array of that - * type; the type string "ai", for example, is the type of an array of - * signed 32-bit integers. - * - `m`: used as a prefix on another type string to mean a "maybe", or - * "nullable", version of that type; the type string "ms", for example, - * is the type of a value that maybe contains a string, or maybe contains - * nothing. - * - `()`: used to enclose zero or more other concatenated type strings to - * create a tuple type; the type string "(is)", for example, is the type of - * a pair of an integer and a string. - * - `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is - * a supertype of any tuple type, regardless of the number of items. - * - `{}`: used to enclose a basic type string concatenated with another type - * string to create a dictionary entry type, which usually appears inside of - * an array to form a dictionary; the type string "a{sd}", for example, is - * the type of a dictionary that maps strings to double precision floating - * point values. - * - * The first type (the basic type) is the key type and the second type is - * the value type. The reason that the first type is restricted to being a - * basic type is so that it can easily be hashed. - * - `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is - * a supertype of all types. Note that, as with all type strings, this - * character represents exactly one type. It cannot be used inside of tuples - * to mean "any number of items". - * - * Any type string of a container that contains an indefinite type is, - * itself, an indefinite type. For example, the type string "a*" - * (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type - * that is a supertype of every array type. "(*s)" is a supertype - * of all tuples that contain exactly two items where the second - * item is a string. - * - * "a{?*}" is an indefinite type that is a supertype of all arrays - * containing dictionary entries where the key is any basic type and - * the value is any type at all. This is, by definition, a dictionary, - * so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note - * that, due to the restriction that the key of a dictionary entry must - * be a basic type, "{**}" is not a valid type string. - */ - - -/** - * SECTION:hash_tables - * @title: Hash Tables - * @short_description: associations between keys and values so that - * given a key the value can be found quickly - * - * A #GHashTable provides associations between keys and values which is - * optimized so that given a key, the associated value can be found, - * inserted or removed in amortized O(1). All operations going through - * each element take O(n) time (list all keys/values, table resize, etc.). - * - * Note that neither keys nor values are copied when inserted into the - * #GHashTable, so they must exist for the lifetime of the #GHashTable. - * This means that the use of static strings is OK, but temporary - * strings (i.e. those created in buffers and those returned by GTK - * widgets) should be copied with g_strdup() before being inserted. - * - * If keys or values are dynamically allocated, you must be careful to - * ensure that they are freed when they are removed from the - * #GHashTable, and also when they are overwritten by new insertions - * into the #GHashTable. It is also not advisable to mix static strings - * and dynamically-allocated strings in a #GHashTable, because it then - * becomes difficult to determine whether the string should be freed. - * - * To create a #GHashTable, use g_hash_table_new(). - * - * To insert a key and value into a #GHashTable, use - * g_hash_table_insert(). - * - * To look up a value corresponding to a given key, use - * g_hash_table_lookup() and g_hash_table_lookup_extended(). - * - * g_hash_table_lookup_extended() can also be used to simply - * check if a key is present in the hash table. - * - * To remove a key and value, use g_hash_table_remove(). - * - * To call a function for each key and value pair use - * g_hash_table_foreach() or use an iterator to iterate over the - * key/value pairs in the hash table, see #GHashTableIter. The iteration order - * of a hash table is not defined, and you must not rely on iterating over - * keys/values in the same order as they were inserted. - * - * To destroy a #GHashTable use g_hash_table_destroy(). - * - * A common use-case for hash tables is to store information about a - * set of keys, without associating any particular value with each - * key. GHashTable optimizes one way of doing so: If you store only - * key-value pairs where key == value, then GHashTable does not - * allocate memory to store the values, which can be a considerable - * space saving, if your set is large. The functions - * g_hash_table_add() and g_hash_table_contains() are designed to be - * used when using #GHashTable this way. - * - * #GHashTable is not designed to be statically initialised with keys and - * values known at compile time. To build a static hash table, use a tool such - * as [gperf](https://www.gnu.org/software/gperf/). - */ - - -/** - * SECTION:hmac - * @title: Secure HMAC Digests - * @short_description: computes the HMAC for data - * - * HMACs should be used when producing a cookie or hash based on data - * and a key. Simple mechanisms for using SHA1 and other algorithms to - * digest a key and data together are vulnerable to various security - * issues. - * [HMAC](http://en.wikipedia.org/wiki/HMAC) - * uses algorithms like SHA1 in a secure way to produce a digest of a - * key and data. - * - * Both the key and data are arbitrary byte arrays of bytes or characters. - * - * Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512 - * in GLib 2.42. Support for SHA-384 was added in GLib 2.52. - */ - - -/** - * SECTION:hooks - * @title: Hook Functions - * @short_description: support for manipulating lists of hook functions - * - * The #GHookList, #GHook and their related functions provide support for - * lists of hook functions. Functions can be added and removed from the lists, - * and the list of hook functions can be invoked. - */ - - -/** - * SECTION:i18n - * @title: Internationalization - * @short_description: gettext support macros - * @see_also: the gettext manual - * - * GLib doesn't force any particular localization method upon its users. - * But since GLib itself is localized using the gettext() mechanism, it seems - * natural to offer the de-facto standard gettext() support macros in an - * easy-to-use form. - * - * In order to use these macros in an application, you must include - * ``. For use in a library, you must include - * `` - * after defining the %GETTEXT_PACKAGE macro suitably for your library: - * |[ - * #define GETTEXT_PACKAGE "gtk20" - * #include - * ]| - * For an application, note that you also have to call bindtextdomain(), - * bind_textdomain_codeset(), textdomain() and setlocale() early on in your - * main() to make gettext() work. For example: - * |[ - * #include - * #include - * - * int - * main (int argc, char **argv) - * { - * setlocale (LC_ALL, ""); - * bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale"); - * bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8"); - * textdomain (GETTEXT_PACKAGE); - * - * // Rest of your application. - * } - * ]| - * where `DATADIR` is as typically provided by automake or Meson. - * - * For a library, you only have to call bindtextdomain() and - * bind_textdomain_codeset() in your initialization function. If your library - * doesn't have an initialization function, you can call the functions before - * the first translated message. - * - * The - * [gettext manual](http://www.gnu.org/software/gettext/manual/gettext.html#Maintainers) - * covers details of how to integrate gettext into a project’s build system and - * workflow. - */ - - -/** - * SECTION:iochannels - * @title: IO Channels - * @short_description: portable support for using files, pipes and sockets - * @see_also: g_io_add_watch(), g_io_add_watch_full(), g_source_remove(), - * #GMainLoop - * - * The #GIOChannel data type aims to provide a portable method for - * using file descriptors, pipes, and sockets, and integrating them - * into the [main event loop][glib-The-Main-Event-Loop]. Currently, - * full support is available on UNIX platforms, support for Windows - * is only partially complete. - * - * To create a new #GIOChannel on UNIX systems use - * g_io_channel_unix_new(). This works for plain file descriptors, - * pipes and sockets. Alternatively, a channel can be created for a - * file in a system independent manner using g_io_channel_new_file(). - * - * Once a #GIOChannel has been created, it can be used in a generic - * manner with the functions g_io_channel_read_chars(), - * g_io_channel_write_chars(), g_io_channel_seek_position(), and - * g_io_channel_shutdown(). - * - * To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop], - * use g_io_add_watch() or g_io_add_watch_full(). Here you specify which - * events you are interested in on the #GIOChannel, and provide a - * function to be called whenever these events occur. - * - * #GIOChannel instances are created with an initial reference count of 1. - * g_io_channel_ref() and g_io_channel_unref() can be used to - * increment or decrement the reference count respectively. When the - * reference count falls to 0, the #GIOChannel is freed. (Though it - * isn't closed automatically, unless it was created using - * g_io_channel_new_file().) Using g_io_add_watch() or - * g_io_add_watch_full() increments a channel's reference count. - * - * The new functions g_io_channel_read_chars(), - * g_io_channel_read_line(), g_io_channel_read_line_string(), - * g_io_channel_read_to_end(), g_io_channel_write_chars(), - * g_io_channel_seek_position(), and g_io_channel_flush() should not be - * mixed with the deprecated functions g_io_channel_read(), - * g_io_channel_write(), and g_io_channel_seek() on the same channel. - */ - - -/** - * SECTION:keyfile - * @title: Key-value file parser - * @short_description: parses .ini-like config files - * - * #GKeyFile lets you parse, edit or create files containing groups of - * key-value pairs, which we call "key files" for lack of a better name. - * Several freedesktop.org specifications use key files now, e.g the - * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) - * and the - * [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec). - * - * The syntax of key files is described in detail in the - * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), - * here is a quick summary: Key files - * consists of groups of key-value pairs, interspersed with comments. - * - * |[ - * # this is just an example - * # there can be comments before the first group - * - * [First Group] - * - * Name=Key File Example\tthis value shows\nescaping - * - * # localized strings are stored in multiple key-value pairs - * Welcome=Hello - * Welcome[de]=Hallo - * Welcome[fr_FR]=Bonjour - * Welcome[it]=Ciao - * Welcome[be@latin]=Hello - * - * [Another Group] - * - * Numbers=2;20;-200;0 - * - * Booleans=true;false;true;true - * ]| - * - * Lines beginning with a '#' and blank lines are considered comments. - * - * Groups are started by a header line containing the group name enclosed - * in '[' and ']', and ended implicitly by the start of the next group or - * the end of the file. Each key-value pair must be contained in a group. - * - * Key-value pairs generally have the form `key=value`, with the - * exception of localized strings, which have the form - * `key[locale]=value`, with a locale identifier of the - * form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER` - * are optional. - * Space before and after the '=' character are ignored. Newline, tab, - * carriage return and backslash characters in value are escaped as \n, - * \t, \r, and \\\\, respectively. To preserve leading spaces in values, - * these can also be escaped as \s. - * - * Key files can store strings (possibly with localized variants), integers, - * booleans and lists of these. Lists are separated by a separator character, - * typically ';' or ','. To use the list separator character in a value in - * a list, it has to be escaped by prefixing it with a backslash. - * - * This syntax is obviously inspired by the .ini files commonly met - * on Windows, but there are some important differences: - * - * - .ini files use the ';' character to begin comments, - * key files use the '#' character. - * - * - Key files do not allow for ungrouped keys meaning only - * comments can precede the first group. - * - * - Key files are always encoded in UTF-8. - * - * - Key and Group names are case-sensitive. For example, a group called - * [GROUP] is a different from [group]. - * - * - .ini files don't have a strongly typed boolean entry type, - * they only have GetProfileInt(). In key files, only - * true and false (in lower case) are allowed. - * - * Note that in contrast to the - * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), - * groups in key files may contain the same - * key multiple times; the last entry wins. Key files may also contain - * multiple groups with the same name; they are merged together. - * Another difference is that keys and group names in key files are not - * restricted to ASCII characters. - * - * Here is an example of loading a key file and reading a value: - * |[ - * g_autoptr(GError) error = NULL; - * g_autoptr(GKeyFile) key_file = g_key_file_new (); - * - * if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error)) - * { - * if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT)) - * g_warning ("Error loading key file: %s", error->message); - * return; - * } - * - * g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error); - * if (val == NULL && - * !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND)) - * { - * g_warning ("Error finding key in key file: %s", error->message); - * return; - * } - * else if (val == NULL) - * { - * // Fall back to a default value. - * val = g_strdup ("default-value"); - * } - * ]| - * - * Here is an example of creating and saving a key file: - * |[ - * g_autoptr(GKeyFile) key_file = g_key_file_new (); - * const gchar *val = …; - * g_autoptr(GError) error = NULL; - * - * g_key_file_set_string (key_file, "Group Name", "SomeKey", val); - * - * // Save as a file. - * if (!g_key_file_save_to_file (key_file, "key-file.ini", &error)) - * { - * g_warning ("Error saving key file: %s", error->message); - * return; - * } - * - * // Or store to a GBytes for use elsewhere. - * gsize data_len; - * g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error); - * if (data == NULL) - * { - * g_warning ("Error saving key file: %s", error->message); - * return; - * } - * g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len); - * ]| - */ - - -/** - * SECTION:linked_lists_double - * @title: Doubly-Linked Lists - * @short_description: linked lists that can be iterated over in both directions - * - * The #GList structure and its associated functions provide a standard - * doubly-linked list data structure. The benefit of this data-structure - * is to provide insertion/deletion operations in O(1) complexity where - * access/search operations are in O(n). The benefit of #GList over - * #GSList (singly linked list) is that the worst case on access/search - * operations is divided by two which comes at a cost in space as we need - * to retain two pointers in place of one. - * - * Each element in the list contains a piece of data, together with - * pointers which link to the previous and next elements in the list. - * Using these pointers it is possible to move through the list in both - * directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists], - * which only allows movement through the list in the forward direction). - * - * The double linked list does not keep track of the number of items - * and does not keep track of both the start and end of the list. If - * you want fast access to both the start and the end of the list, - * and/or the number of items in the list, use a - * [GQueue][glib-Double-ended-Queues] instead. - * - * The data contained in each element can be either integer values, by - * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], - * or simply pointers to any type of data. - * - * List elements are allocated from the [slice allocator][glib-Memory-Slices], - * which is more efficient than allocating elements individually. - * - * Note that most of the #GList functions expect to be passed a pointer - * to the first element in the list. The functions which insert - * elements return the new start of the list, which may have changed. - * - * There is no function to create a #GList. %NULL is considered to be - * a valid, empty list so you simply set a #GList* to %NULL to initialize - * it. - * - * To add elements, use g_list_append(), g_list_prepend(), - * g_list_insert() and g_list_insert_sorted(). - * - * To visit all elements in the list, use a loop over the list: - * |[ - * GList *l; - * for (l = list; l != NULL; l = l->next) - * { - * // do something with l->data - * } - * ]| - * - * To call a function for each element in the list, use g_list_foreach(). - * - * To loop over the list and modify it (e.g. remove a certain element) - * a while loop is more appropriate, for example: - * |[ - * GList *l = list; - * while (l != NULL) - * { - * GList *next = l->next; - * if (should_be_removed (l)) - * { - * // possibly free l->data - * list = g_list_delete_link (list, l); - * } - * l = next; - * } - * ]| - * - * To remove elements, use g_list_remove(). - * - * To navigate in a list, use g_list_first(), g_list_last(), - * g_list_next(), g_list_previous(). - * - * To find elements in the list use g_list_nth(), g_list_nth_data(), - * g_list_find() and g_list_find_custom(). - * - * To find the index of an element use g_list_position() and - * g_list_index(). - * - * To free the entire list, use g_list_free() or g_list_free_full(). - */ - - -/** - * SECTION:linked_lists_single - * @title: Singly-Linked Lists - * @short_description: linked lists that can be iterated in one direction - * - * The #GSList structure and its associated functions provide a - * standard singly-linked list data structure. The benefit of this - * data-structure is to provide insertion/deletion operations in O(1) - * complexity where access/search operations are in O(n). The benefit - * of #GSList over #GList (doubly linked list) is that they are lighter - * in space as they only need to retain one pointer but it double the - * cost of the worst case access/search operations. - * - * Each element in the list contains a piece of data, together with a - * pointer which links to the next element in the list. Using this - * pointer it is possible to move through the list in one direction - * only (unlike the [double-linked lists][glib-Doubly-Linked-Lists], - * which allow movement in both directions). - * - * The data contained in each element can be either integer values, by - * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], - * or simply pointers to any type of data. - * - * List elements are allocated from the [slice allocator][glib-Memory-Slices], - * which is more efficient than allocating elements individually. - * - * Note that most of the #GSList functions expect to be passed a - * pointer to the first element in the list. The functions which insert - * elements return the new start of the list, which may have changed. - * - * There is no function to create a #GSList. %NULL is considered to be - * the empty list so you simply set a #GSList* to %NULL. - * - * To add elements, use g_slist_append(), g_slist_prepend(), - * g_slist_insert() and g_slist_insert_sorted(). - * - * To remove elements, use g_slist_remove(). - * - * To find elements in the list use g_slist_last(), g_slist_next(), - * g_slist_nth(), g_slist_nth_data(), g_slist_find() and - * g_slist_find_custom(). - * - * To find the index of an element use g_slist_position() and - * g_slist_index(). - * - * To call a function for each element in the list use - * g_slist_foreach(). - * - * To free the entire list, use g_slist_free(). - */ - - -/** - * SECTION:macros - * @title: Standard Macros - * @short_description: commonly-used macros - * - * These macros provide a few commonly-used features. - */ - - -/** - * SECTION:macros_misc - * @title: Miscellaneous Macros - * @short_description: specialized macros which are not used often - * - * These macros provide more specialized features which are not - * needed so often by application programmers. - */ - - -/** - * SECTION:main - * @title: The Main Event Loop - * @short_description: manages all available sources of events - * - * The main event loop manages all the available sources of events for - * GLib and GTK+ applications. These events can come from any number of - * different types of sources such as file descriptors (plain files, - * pipes or sockets) and timeouts. New types of event sources can also - * be added using g_source_attach(). - * - * To allow multiple independent sets of sources to be handled in - * different threads, each source is associated with a #GMainContext. - * A #GMainContext can only be running in a single thread, but - * sources can be added to it and removed from it from other threads. All - * functions which operate on a #GMainContext or a built-in #GSource are - * thread-safe. - * - * Each event source is assigned a priority. The default priority, - * %G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. - * Values greater than 0 denote lower priorities. Events from high priority - * sources are always processed before events from lower priority sources. - * - * Idle functions can also be added, and assigned a priority. These will - * be run whenever no events with a higher priority are ready to be processed. - * - * The #GMainLoop data type represents a main event loop. A GMainLoop is - * created with g_main_loop_new(). After adding the initial event sources, - * g_main_loop_run() is called. This continuously checks for new events from - * each of the event sources and dispatches them. Finally, the processing of - * an event from one of the sources leads to a call to g_main_loop_quit() to - * exit the main loop, and g_main_loop_run() returns. - * - * It is possible to create new instances of #GMainLoop recursively. - * This is often used in GTK+ applications when showing modal dialog - * boxes. Note that event sources are associated with a particular - * #GMainContext, and will be checked and dispatched for all main - * loops associated with that GMainContext. - * - * GTK+ contains wrappers of some of these functions, e.g. gtk_main(), - * gtk_main_quit() and gtk_events_pending(). - * - * ## Creating new source types - * - * One of the unusual features of the #GMainLoop functionality - * is that new types of event source can be created and used in - * addition to the builtin type of event source. A new event source - * type is used for handling GDK events. A new source type is created - * by "deriving" from the #GSource structure. The derived type of - * source is represented by a structure that has the #GSource structure - * as a first element, and other elements specific to the new source - * type. To create an instance of the new source type, call - * g_source_new() passing in the size of the derived structure and - * a table of functions. These #GSourceFuncs determine the behavior of - * the new source type. - * - * New source types basically interact with the main context - * in two ways. Their prepare function in #GSourceFuncs can set a timeout - * to determine the maximum amount of time that the main loop will sleep - * before checking the source again. In addition, or as well, the source - * can add file descriptors to the set that the main context checks using - * g_source_add_poll(). - * - * ## Customizing the main loop iteration - * - * Single iterations of a #GMainContext can be run with - * g_main_context_iteration(). In some cases, more detailed control - * of exactly how the details of the main loop work is desired, for - * instance, when integrating the #GMainLoop with an external main loop. - * In such cases, you can call the component functions of - * g_main_context_iteration() directly. These functions are - * g_main_context_prepare(), g_main_context_query(), - * g_main_context_check() and g_main_context_dispatch(). - * - * ## State of a Main Context # {#mainloop-states} - * - * The operation of these functions can best be seen in terms - * of a state diagram, as shown in this image. - * - * ![](mainloop-states.gif) - * - * On UNIX, the GLib mainloop is incompatible with fork(). Any program - * using the mainloop must either exec() or exit() from the child - * without returning to the mainloop. - * - * ## Memory management of sources # {#mainloop-memory-management} - * - * There are two options for memory management of the user data passed to a - * #GSource to be passed to its callback on invocation. This data is provided - * in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and - * more generally, using g_source_set_callback(). This data is typically an - * object which ‘owns’ the timeout or idle callback, such as a widget or a - * network protocol implementation. In many cases, it is an error for the - * callback to be invoked after this owning object has been destroyed, as that - * results in use of freed memory. - * - * The first, and preferred, option is to store the source ID returned by - * functions such as g_timeout_add() or g_source_attach(), and explicitly - * remove that source from the main context using g_source_remove() when the - * owning object is finalized. This ensures that the callback can only be - * invoked while the object is still alive. - * - * The second option is to hold a strong reference to the object in the - * callback, and to release it in the callback’s #GDestroyNotify. This ensures - * that the object is kept alive until after the source is finalized, which is - * guaranteed to be after it is invoked for the final time. The #GDestroyNotify - * is another callback passed to the ‘full’ variants of #GSource functions (for - * example, g_timeout_add_full()). It is called when the source is finalized, - * and is designed for releasing references like this. - * - * One important caveat of this second approach is that it will keep the object - * alive indefinitely if the main loop is stopped before the #GSource is - * invoked, which may be undesirable. - */ - - -/** - * SECTION:markup - * @Title: Simple XML Subset Parser - * @Short_description: parses a subset of XML - * @See_also: [XML Specification](http://www.w3.org/TR/REC-xml/) - * - * The "GMarkup" parser is intended to parse a simple markup format - * that's a subset of XML. This is a small, efficient, easy-to-use - * parser. It should not be used if you expect to interoperate with - * other applications generating full-scale XML, and must not be used if you - * expect to parse untrusted input. However, it's very - * useful for application data files, config files, etc. where you - * know your application will be the only one writing the file. - * Full-scale XML parsers should be able to parse the subset used by - * GMarkup, so you can easily migrate to full-scale XML at a later - * time if the need arises. - * - * GMarkup is not guaranteed to signal an error on all invalid XML; - * the parser may accept documents that an XML parser would not. - * However, XML documents which are not well-formed (which is a - * weaker condition than being valid. See the - * [XML specification](http://www.w3.org/TR/REC-xml/) - * for definitions of these terms.) are not considered valid GMarkup - * documents. - * - * Simplifications to XML include: - * - * - Only UTF-8 encoding is allowed - * - * - No user-defined entities - * - * - Processing instructions, comments and the doctype declaration - * are "passed through" but are not interpreted in any way - * - * - No DTD or validation - * - * The markup format does support: - * - * - Elements - * - * - Attributes - * - * - 5 standard entities: & < > " ' - * - * - Character references - * - * - Sections marked as CDATA - */ - - -/** - * SECTION:memory - * @Short_Description: general memory-handling - * @Title: Memory Allocation - * - * These functions provide support for allocating and freeing memory. - * - * If any call to allocate memory using functions g_new(), g_new0(), g_renew(), - * g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n() - * fails, the application is terminated. This also means that there is no - * need to check if the call succeeded. On the other hand, the `g_try_...()` family - * of functions returns %NULL on failure that can be used as a check - * for unsuccessful memory allocation. The application is not terminated - * in this case. - * - * As all GLib functions and data structures use `g_malloc()` internally, unless - * otherwise specified, any allocation failure will result in the application - * being terminated. - * - * It's important to match g_malloc() (and wrappers such as g_new()) with - * g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with - * g_slice_free(), plain malloc() with free(), and (if you're using C++) - * new with delete and new[] with delete[]. Otherwise bad things can happen, - * since these allocators may use different memory pools (and new/delete call - * constructors and destructors). - * - * Since GLib 2.46 g_malloc() is hardcoded to always use the system malloc - * implementation. - */ - - -/** - * SECTION:memory_slices - * @title: Memory Slices - * @short_description: efficient way to allocate groups of equal-sized - * chunks of memory - * - * Memory slices provide a space-efficient and multi-processing scalable - * way to allocate equal-sized pieces of memory, just like the original - * #GMemChunks (from GLib 2.8), while avoiding their excessive - * memory-waste, scalability and performance problems. - * - * To achieve these goals, the slice allocator uses a sophisticated, - * layered design that has been inspired by Bonwick's slab allocator - * ([Bonwick94](http://citeseer.ist.psu.edu/bonwick94slab.html) - * Jeff Bonwick, The slab allocator: An object-caching kernel - * memory allocator. USENIX 1994, and - * [Bonwick01](http://citeseer.ist.psu.edu/bonwick01magazines.html) - * Bonwick and Jonathan Adams, Magazines and vmem: Extending the - * slab allocator to many cpu's and arbitrary resources. USENIX 2001) - * - * It uses posix_memalign() to optimize allocations of many equally-sized - * chunks, and has per-thread free lists (the so-called magazine layer) - * to quickly satisfy allocation requests of already known structure sizes. - * This is accompanied by extra caching logic to keep freed memory around - * for some time before returning it to the system. Memory that is unused - * due to alignment constraints is used for cache colorization (random - * distribution of chunk addresses) to improve CPU cache utilization. The - * caching layer of the slice allocator adapts itself to high lock contention - * to improve scalability. - * - * The slice allocator can allocate blocks as small as two pointers, and - * unlike malloc(), it does not reserve extra space per block. For large block - * sizes, g_slice_new() and g_slice_alloc() will automatically delegate to the - * system malloc() implementation. For newly written code it is recommended - * to use the new `g_slice` API instead of g_malloc() and - * friends, as long as objects are not resized during their lifetime and the - * object size used at allocation time is still available when freeing. - * - * Here is an example for using the slice allocator: - * |[ - * gchar *mem[10000]; - * gint i; - * - * // Allocate 10000 blocks. - * for (i = 0; i < 10000; i++) - * { - * mem[i] = g_slice_alloc (50); - * - * // Fill in the memory with some junk. - * for (j = 0; j < 50; j++) - * mem[i][j] = i * j; - * } - * - * // Now free all of the blocks. - * for (i = 0; i < 10000; i++) - * g_slice_free1 (50, mem[i]); - * ]| - * - * And here is an example for using the using the slice allocator - * with data structures: - * |[ - * GRealArray *array; - * - * // Allocate one block, using the g_slice_new() macro. - * array = g_slice_new (GRealArray); - * - * // We can now use array just like a normal pointer to a structure. - * array->data = NULL; - * array->len = 0; - * array->alloc = 0; - * array->zero_terminated = (zero_terminated ? 1 : 0); - * array->clear = (clear ? 1 : 0); - * array->elt_size = elt_size; - * - * // We can free the block, so it can be reused. - * g_slice_free (GRealArray, array); - * ]| - */ - - -/** - * SECTION:messages - * @Title: Message Output and Debugging Functions - * @Short_description: functions to output messages and help debug applications - * - * These functions provide support for outputting messages. - * - * The g_return family of macros (g_return_if_fail(), - * g_return_val_if_fail(), g_return_if_reached(), - * g_return_val_if_reached()) should only be used for programming - * errors, a typical use case is checking for invalid parameters at - * the beginning of a public function. They should not be used if - * you just mean "if (error) return", they should only be used if - * you mean "if (bug in program) return". The program behavior is - * generally considered undefined after one of these checks fails. - * They are not intended for normal control flow, only to give a - * perhaps-helpful warning before giving up. - * - * Structured logging output is supported using g_log_structured(). This differs - * from the traditional g_log() API in that log messages are handled as a - * collection of key–value pairs representing individual pieces of information, - * rather than as a single string containing all the information in an arbitrary - * format. - * - * The convenience macros g_info(), g_message(), g_debug(), g_warning() and g_error() - * will use the traditional g_log() API unless you define the symbol - * %G_LOG_USE_STRUCTURED before including `glib.h`. But note that even messages - * logged through the traditional g_log() API are ultimatively passed to - * g_log_structured(), so that all log messages end up in same destination. - * If %G_LOG_USE_STRUCTURED is defined, g_test_expect_message() will become - * ineffective for the wrapper macros g_warning() and friends (see - * [Testing for Messages][testing-for-messages]). - * - * The support for structured logging was motivated by the following needs (some - * of which were supported previously; others weren’t): - * * Support for multiple logging levels. - * * Structured log support with the ability to add `MESSAGE_ID`s (see - * g_log_structured()). - * * Moving the responsibility for filtering log messages from the program to - * the log viewer — instead of libraries and programs installing log handlers - * (with g_log_set_handler()) which filter messages before output, all log - * messages are outputted, and the log viewer program (such as `journalctl`) - * must filter them. This is based on the idea that bugs are sometimes hard - * to reproduce, so it is better to log everything possible and then use - * tools to analyse the logs than it is to not be able to reproduce a bug to - * get additional log data. Code which uses logging in performance-critical - * sections should compile out the g_log_structured() calls in - * release builds, and compile them in in debugging builds. - * * A single writer function which handles all log messages in a process, from - * all libraries and program code; rather than multiple log handlers with - * poorly defined interactions between them. This allows a program to easily - * change its logging policy by changing the writer function, for example to - * log to an additional location or to change what logging output fallbacks - * are used. The log writer functions provided by GLib are exposed publicly - * so they can be used from programs’ log writers. This allows log writer - * policy and implementation to be kept separate. - * * If a library wants to add standard information to all of its log messages - * (such as library state) or to redact private data (such as passwords or - * network credentials), it should use a wrapper function around its - * g_log_structured() calls or implement that in the single log writer - * function. - * * If a program wants to pass context data from a g_log_structured() call to - * its log writer function so that, for example, it can use the correct - * server connection to submit logs to, that user data can be passed as a - * zero-length #GLogField to g_log_structured_array(). - * * Color output needed to be supported on the terminal, to make reading - * through logs easier. - * - * ## Using Structured Logging ## {#using-structured-logging} - * - * To use structured logging (rather than the old-style logging), either use - * the g_log_structured() and g_log_structured_array() functions; or define - * `G_LOG_USE_STRUCTURED` before including any GLib header, and use the - * g_message(), g_debug(), g_error() (etc.) macros. - * - * You do not need to define `G_LOG_USE_STRUCTURED` to use g_log_structured(), - * but it is a good idea to avoid confusion. - * - * ## Log Domains ## {#log-domains} - * - * Log domains may be used to broadly split up the origins of log messages. - * Typically, there are one or a few log domains per application or library. - * %G_LOG_DOMAIN should be used to define the default log domain for the current - * compilation unit — it is typically defined at the top of a source file, or in - * the preprocessor flags for a group of source files. - * - * Log domains must be unique, and it is recommended that they are the - * application or library name, optionally followed by a hyphen and a sub-domain - * name. For example, `bloatpad` or `bloatpad-io`. - * - * ## Debug Message Output ## {#debug-message-output} - * - * The default log functions (g_log_default_handler() for the old-style API and - * g_log_writer_default() for the structured API) both drop debug and - * informational messages by default, unless the log domains of those messages - * are listed in the `G_MESSAGES_DEBUG` environment variable (or it is set to - * `all`). - * - * It is recommended that custom log writer functions re-use the - * `G_MESSAGES_DEBUG` environment variable, rather than inventing a custom one, - * so that developers can re-use the same debugging techniques and tools across - * projects. Since GLib 2.68, this can be implemented by dropping messages - * for which g_log_writer_default_would_drop() returns %TRUE. - * - * ## Testing for Messages ## {#testing-for-messages} - * - * With the old g_log() API, g_test_expect_message() and - * g_test_assert_expected_messages() could be used in simple cases to check - * whether some code under test had emitted a given log message. These - * functions have been deprecated with the structured logging API, for several - * reasons: - * * They relied on an internal queue which was too inflexible for many use - * cases, where messages might be emitted in several orders, some - * messages might not be emitted deterministically, or messages might be - * emitted by unrelated log domains. - * * They do not support structured log fields. - * * Examining the log output of code is a bad approach to testing it, and - * while it might be necessary for legacy code which uses g_log(), it should - * be avoided for new code using g_log_structured(). - * - * They will continue to work as before if g_log() is in use (and - * %G_LOG_USE_STRUCTURED is not defined). They will do nothing if used with the - * structured logging API. - * - * Examining the log output of code is discouraged: libraries should not emit to - * `stderr` during defined behaviour, and hence this should not be tested. If - * the log emissions of a library during undefined behaviour need to be tested, - * they should be limited to asserting that the library aborts and prints a - * suitable error message before aborting. This should be done with - * g_test_trap_assert_stderr(). - * - * If it is really necessary to test the structured log messages emitted by a - * particular piece of code – and the code cannot be restructured to be more - * suitable to more conventional unit testing – you should write a custom log - * writer function (see g_log_set_writer_func()) which appends all log messages - * to a queue. When you want to check the log messages, examine and clear the - * queue, ignoring irrelevant log messages (for example, from log domains other - * than the one under test). - */ - - -/** - * SECTION:misc_utils - * @title: Miscellaneous Utility Functions - * @short_description: a selection of portable utility functions - * - * These are portable utility functions. - */ - - -/** - * SECTION:numerical - * @title: Numerical Definitions - * @short_description: mathematical constants, and floating point decomposition - * - * GLib offers mathematical constants such as #G_PI for the value of pi; - * many platforms have these in the C library, but some don't, the GLib - * versions always exist. - * - * The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the - * sign, mantissa and exponent of IEEE floats and doubles. These unions are - * defined as appropriate for a given platform. IEEE floats and doubles are - * supported (used for storage) by at least Intel, PPC and Sparc. See - * [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float) - * for more information about IEEE number formats. - */ - - -/** - * SECTION:option - * @Short_description: parses commandline options - * @Title: Commandline option parser - * - * The GOption commandline parser is intended to be a simpler replacement - * for the popt library. It supports short and long commandline options, - * as shown in the following example: - * - * `testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2` - * - * The example demonstrates a number of features of the GOption - * commandline parser: - * - * - Options can be single letters, prefixed by a single dash. - * - * - Multiple short options can be grouped behind a single dash. - * - * - Long options are prefixed by two consecutive dashes. - * - * - Options can have an extra argument, which can be a number, a string or - * a filename. For long options, the extra argument can be appended with - * an equals sign after the option name, which is useful if the extra - * argument starts with a dash, which would otherwise cause it to be - * interpreted as another option. - * - * - Non-option arguments are returned to the application as rest arguments. - * - * - An argument consisting solely of two dashes turns off further parsing, - * any remaining arguments (even those starting with a dash) are returned - * to the application as rest arguments. - * - * Another important feature of GOption is that it can automatically - * generate nicely formatted help output. Unless it is explicitly turned - * off with g_option_context_set_help_enabled(), GOption will recognize - * the `--help`, `-?`, `--help-all` and `--help-groupname` options - * (where `groupname` is the name of a #GOptionGroup) and write a text - * similar to the one shown in the following example to stdout. - * - * |[ - * Usage: - * testtreemodel [OPTION...] - test tree model performance - * - * Help Options: - * -h, --help Show help options - * --help-all Show all help options - * --help-gtk Show GTK+ Options - * - * Application Options: - * -r, --repeats=N Average over N repetitions - * -m, --max-size=M Test up to 2^M items - * --display=DISPLAY X display to use - * -v, --verbose Be verbose - * -b, --beep Beep when done - * --rand Randomize the data - * ]| - * - * GOption groups options in #GOptionGroups, which makes it easy to - * incorporate options from multiple sources. The intended use for this is - * to let applications collect option groups from the libraries it uses, - * add them to their #GOptionContext, and parse all options by a single call - * to g_option_context_parse(). See gtk_get_option_group() for an example. - * - * If an option is declared to be of type string or filename, GOption takes - * care of converting it to the right encoding; strings are returned in - * UTF-8, filenames are returned in the GLib filename encoding. Note that - * this only works if setlocale() has been called before - * g_option_context_parse(). - * - * Here is a complete example of setting up GOption to parse the example - * commandline above and produce the example help output. - * |[ - * static gint repeats = 2; - * static gint max_size = 8; - * static gboolean verbose = FALSE; - * static gboolean beep = FALSE; - * static gboolean randomize = FALSE; - * - * static GOptionEntry entries[] = - * { - * { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" }, - * { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" }, - * { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL }, - * { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL }, - * { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL }, - * G_OPTION_ENTRY_NULL - * }; - * - * int - * main (int argc, char *argv[]) - * { - * GError *error = NULL; - * GOptionContext *context; - * - * context = g_option_context_new ("- test tree model performance"); - * g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE); - * g_option_context_add_group (context, gtk_get_option_group (TRUE)); - * if (!g_option_context_parse (context, &argc, &argv, &error)) - * { - * g_print ("option parsing failed: %s\n", error->message); - * exit (1); - * } - * - * ... - * - * } - * ]| - * - * On UNIX systems, the argv that is passed to main() has no particular - * encoding, even to the extent that different parts of it may have - * different encodings. In general, normal arguments and flags will be - * in the current locale and filenames should be considered to be opaque - * byte strings. Proper use of %G_OPTION_ARG_FILENAME vs - * %G_OPTION_ARG_STRING is therefore important. - * - * Note that on Windows, filenames do have an encoding, but using - * #GOptionContext with the argv as passed to main() will result in a - * program that can only accept commandline arguments with characters - * from the system codepage. This can cause problems when attempting to - * deal with filenames containing Unicode characters that fall outside - * of the codepage. - * - * A solution to this is to use g_win32_get_command_line() and - * g_option_context_parse_strv() which will properly handle full Unicode - * filenames. If you are using #GApplication, this is done - * automatically for you. - * - * The following example shows how you can use #GOptionContext directly - * in order to correctly deal with Unicode filenames on Windows: - * - * |[ - * int - * main (int argc, char **argv) - * { - * GError *error = NULL; - * GOptionContext *context; - * gchar **args; - * - * #ifdef G_OS_WIN32 - * args = g_win32_get_command_line (); - * #else - * args = g_strdupv (argv); - * #endif - * - * // set up context - * - * if (!g_option_context_parse_strv (context, &args, &error)) - * { - * // error happened - * } - * - * ... - * - * g_strfreev (args); - * - * ... - * } - * ]| - */ - - -/** - * SECTION:patterns - * @title: Glob-style pattern matching - * @short_description: matches strings against patterns containing '*' - * (wildcard) and '?' (joker) - * - * The g_pattern_match* functions match a string - * against a pattern containing '*' and '?' wildcards with similar - * semantics as the standard glob() function: '*' matches an arbitrary, - * possibly empty, string, '?' matches an arbitrary character. - * - * Note that in contrast to glob(), the '/' character can be matched by - * the wildcards, there are no '[...]' character ranges and '*' and '?' - * can not be escaped to include them literally in a pattern. - * - * When multiple strings must be matched against the same pattern, it - * is better to compile the pattern to a #GPatternSpec using - * g_pattern_spec_new() and use g_pattern_match_string() instead of - * g_pattern_match_simple(). This avoids the overhead of repeated - * pattern compilation. - */ - - -/** - * SECTION:quarks - * @title: Quarks - * @short_description: a 2-way association between a string and a - * unique integer identifier - * - * Quarks are associations between strings and integer identifiers. - * Given either the string or the #GQuark identifier it is possible to - * retrieve the other. - * - * Quarks are used for both [datasets][glib-Datasets] and - * [keyed data lists][glib-Keyed-Data-Lists]. - * - * To create a new quark from a string, use g_quark_from_string() or - * g_quark_from_static_string(). - * - * To find the string corresponding to a given #GQuark, use - * g_quark_to_string(). - * - * To find the #GQuark corresponding to a given string, use - * g_quark_try_string(). - * - * Another use for the string pool maintained for the quark functions - * is string interning, using g_intern_string() or - * g_intern_static_string(). An interned string is a canonical - * representation for a string. One important advantage of interned - * strings is that they can be compared for equality by a simple - * pointer comparison, rather than using strcmp(). - */ - - -/** - * SECTION:queue - * @Title: Double-ended Queues - * @Short_description: double-ended queue data structure - * - * The #GQueue structure and its associated functions provide a standard - * queue data structure. Internally, GQueue uses the same data structure - * as #GList to store elements with the same complexity over - * insertion/deletion (O(1)) and access/search (O(n)) operations. - * - * The data contained in each element can be either integer values, by - * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], - * or simply pointers to any type of data. - * - * As with all other GLib data structures, #GQueue is not thread-safe. - * For a thread-safe queue, use #GAsyncQueue. - * - * To create a new GQueue, use g_queue_new(). - * - * To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or - * g_queue_init(). - * - * To add elements, use g_queue_push_head(), g_queue_push_head_link(), - * g_queue_push_tail() and g_queue_push_tail_link(). - * - * To remove elements, use g_queue_pop_head() and g_queue_pop_tail(). - * - * To free the entire queue, use g_queue_free(). - */ - - -/** - * SECTION:random_numbers - * @title: Random Numbers - * @short_description: pseudo-random number generator - * - * The following functions allow you to use a portable, fast and good - * pseudo-random number generator (PRNG). - * - * Do not use this API for cryptographic purposes such as key - * generation, nonces, salts or one-time pads. - * - * This PRNG is suitable for non-cryptographic use such as in games - * (shuffling a card deck, generating levels), generating data for - * a test suite, etc. If you need random data for cryptographic - * purposes, it is recommended to use platform-specific APIs such - * as `/dev/random` on UNIX, or CryptGenRandom() on Windows. - * - * GRand uses the Mersenne Twister PRNG, which was originally - * developed by Makoto Matsumoto and Takuji Nishimura. Further - * information can be found at - * [this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html). - * - * If you just need a random number, you simply call the g_random_* - * functions, which will create a globally used #GRand and use the - * according g_rand_* functions internally. Whenever you need a - * stream of reproducible random numbers, you better create a - * #GRand yourself and use the g_rand_* functions directly, which - * will also be slightly faster. Initializing a #GRand with a - * certain seed will produce exactly the same series of random - * numbers on all platforms. This can thus be used as a seed for - * e.g. games. - * - * The g_rand*_range functions will return high quality equally - * distributed random numbers, whereas for example the - * `(g_random_int()%max)` approach often - * doesn't yield equally distributed numbers. - * - * GLib changed the seeding algorithm for the pseudo-random number - * generator Mersenne Twister, as used by #GRand. This was necessary, - * because some seeds would yield very bad pseudo-random streams. - * Also the pseudo-random integers generated by g_rand*_int_range() - * will have a slightly better equal distribution with the new - * version of GLib. - * - * The original seeding and generation algorithms, as found in - * GLib 2.0.x, can be used instead of the new ones by setting the - * environment variable `G_RANDOM_VERSION` to the value of '2.0'. - * Use the GLib-2.0 algorithms only if you have sequences of numbers - * generated with Glib-2.0 that you need to reproduce exactly. - */ - - -/** - * SECTION:rcbox - * @Title: Reference counted data - * @Short_description: Allocated memory with reference counting semantics - * - * A "reference counted box", or "RcBox", is an opaque wrapper data type - * that is guaranteed to be as big as the size of a given data type, and - * which augments the given data type with reference counting semantics - * for its memory management. - * - * RcBox is useful if you have a plain old data type, like a structure - * typically placed on the stack, and you wish to provide additional API - * to use it on the heap; or if you want to implement a new type to be - * passed around by reference without necessarily implementing copy/free - * semantics or your own reference counting. - * - * The typical use is: - * - * |[ - * typedef struct { - * char *name; - * char *address; - * char *city; - * char *state; - * int age; - * } Person; - * - * Person * - * person_new (void) - * { - * return g_rc_box_new0 (Person); - * } - * ]| - * - * Every time you wish to acquire a reference on the memory, you should - * call g_rc_box_acquire(); similarly, when you wish to release a reference - * you should call g_rc_box_release(): - * - * |[ - * // Add a Person to the Database; the Database acquires ownership - * // of the Person instance - * void - * add_person_to_database (Database *db, Person *p) - * { - * db->persons = g_list_prepend (db->persons, g_rc_box_acquire (p)); - * } - * - * // Removes a Person from the Database; the reference acquired by - * // add_person_to_database() is released here - * void - * remove_person_from_database (Database *db, Person *p) - * { - * db->persons = g_list_remove (db->persons, p); - * g_rc_box_release (p); - * } - * ]| - * - * If you have additional memory allocated inside the structure, you can - * use g_rc_box_release_full(), which takes a function pointer, which - * will be called if the reference released was the last: - * - * |[ - * void - * person_clear (Person *p) - * { - * g_free (p->name); - * g_free (p->address); - * g_free (p->city); - * g_free (p->state); - * } - * - * void - * remove_person_from_database (Database *db, Person *p) - * { - * db->persons = g_list_remove (db->persons, p); - * g_rc_box_release_full (p, (GDestroyNotify) person_clear); - * } - * ]| - * - * If you wish to transfer the ownership of a reference counted data - * type without increasing the reference count, you can use g_steal_pointer(): - * - * |[ - * Person *p = g_rc_box_new (Person); - * - * // fill_person_details() is defined elsewhere - * fill_person_details (p); - * - * // add_person_to_database_no_ref() is defined elsewhere; it adds - * // a Person to the Database without taking a reference - * add_person_to_database_no_ref (db, g_steal_pointer (&p)); - * ]| - * - * ## Thread safety - * - * The reference counting operations on data allocated using g_rc_box_alloc(), - * g_rc_box_new(), and g_rc_box_dup() are not thread safe; it is your code's - * responsibility to ensure that references are acquired are released on the - * same thread. - * - * If you need thread safe reference counting, see the [atomic reference counted - * data][arcbox] API. - * - * ## Automatic pointer clean up - * - * If you want to add g_autoptr() support to your plain old data type through - * reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and - * g_rc_box_release(): - * - * |[ - * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_rc_box_release) - * ]| - * - * If you need to clear the contents of the data, you will need to use an - * ancillary function that calls g_rc_box_release_full(): - * - * |[ - * static void - * my_data_struct_release (MyDataStruct *data) - * { - * // my_data_struct_clear() is defined elsewhere - * g_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); - * } - * - * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release) - * ]| - * - * Since: 2.58 - */ - - -/** - * SECTION:refcount - * @Title: Reference counting - * @Short_description: Reference counting types and functions - * - * Reference counting is a garbage collection mechanism that is based on - * assigning a counter to a data type, or any memory area; the counter is - * increased whenever a new reference to that data type is acquired, and - * decreased whenever the reference is released. Once the last reference - * is released, the resources associated to that data type are freed. - * - * GLib uses reference counting in many of its data types, and provides - * the #grefcount and #gatomicrefcount types to implement safe and atomic - * reference counting semantics in new data types. - * - * It is important to note that #grefcount and #gatomicrefcount should be - * considered completely opaque types; you should always use the provided - * API to increase and decrease the counters, and you should never check - * their content directly, or compare their content with other values. - * - * Since: 2.58 - */ - - -/** - * SECTION:refstring - * @Title: Reference counted strings - * @Short_description: Strings with reference counted memory management - * - * Reference counted strings are normal C strings that have been augmented - * with a reference counter to manage their resources. You allocate a new - * reference counted string and acquire and release references as needed, - * instead of copying the string among callers; when the last reference on - * the string is released, the resources allocated for it are freed. - * - * Typically, reference counted strings can be used when parsing data from - * files and storing them into data structures that are passed to various - * callers: - * - * |[ - * PersonDetails * - * person_details_from_data (const char *data) - * { - * // Use g_autoptr() to simplify error cases - * g_autoptr(GRefString) full_name = NULL; - * g_autoptr(GRefString) address = NULL; - * g_autoptr(GRefString) city = NULL; - * g_autoptr(GRefString) state = NULL; - * g_autoptr(GRefString) zip_code = NULL; - * - * // parse_person_details() is defined elsewhere; returns refcounted strings - * if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code)) - * return NULL; - * - * if (!validate_zip_code (zip_code)) - * return NULL; - * - * // add_address_to_cache() and add_full_name_to_cache() are defined - * // elsewhere; they add strings to various caches, using refcounted - * // strings to avoid copying data over and over again - * add_address_to_cache (address, city, state, zip_code); - * add_full_name_to_cache (full_name); - * - * // person_details_new() is defined elsewhere; it takes a reference - * // on each string - * PersonDetails *res = person_details_new (full_name, - * address, - * city, - * state, - * zip_code); - * - * return res; - * } - * ]| - * - * In the example above, we have multiple functions taking the same strings - * for different uses; with typical C strings, we'd have to copy the strings - * every time the life time rules of the data differ from the life time of - * the string parsed from the original buffer. With reference counted strings, - * each caller can take a reference on the data, and keep it as long as it - * needs to own the string. - * - * Reference counted strings can also be "interned" inside a global table - * owned by GLib; while an interned string has at least a reference, creating - * a new interned reference counted string with the same contents will return - * a reference to the existing string instead of creating a new reference - * counted string instance. Once the string loses its last reference, it will - * be automatically removed from the global interned strings table. - * - * Since: 2.58 - */ - - -/** - * SECTION:scanner - * @title: Lexical Scanner - * @short_description: a general purpose lexical scanner - * - * The #GScanner and its associated functions provide a - * general purpose lexical scanner. - */ - - -/** - * SECTION:sequence - * @title: Sequences - * @short_description: scalable lists - * - * The #GSequence data structure has the API of a list, but is - * implemented internally with a balanced binary tree. This means that - * most of the operations (access, search, insertion, deletion, ...) on - * #GSequence are O(log(n)) in average and O(n) in worst case for time - * complexity. But, note that maintaining a balanced sorted list of n - * elements is done in time O(n log(n)). - * The data contained in each element can be either integer values, by using - * of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply - * pointers to any type of data. - * - * A #GSequence is accessed through "iterators", represented by a - * #GSequenceIter. An iterator represents a position between two - * elements of the sequence. For example, the "begin" iterator - * represents the gap immediately before the first element of the - * sequence, and the "end" iterator represents the gap immediately - * after the last element. In an empty sequence, the begin and end - * iterators are the same. - * - * Some methods on #GSequence operate on ranges of items. For example - * g_sequence_foreach_range() will call a user-specified function on - * each element with the given range. The range is delimited by the - * gaps represented by the passed-in iterators, so if you pass in the - * begin and end iterators, the range in question is the entire - * sequence. - * - * The function g_sequence_get() is used with an iterator to access the - * element immediately following the gap that the iterator represents. - * The iterator is said to "point" to that element. - * - * Iterators are stable across most operations on a #GSequence. For - * example an iterator pointing to some element of a sequence will - * continue to point to that element even after the sequence is sorted. - * Even moving an element to another sequence using for example - * g_sequence_move_range() will not invalidate the iterators pointing - * to it. The only operation that will invalidate an iterator is when - * the element it points to is removed from any sequence. - * - * To sort the data, either use g_sequence_insert_sorted() or - * g_sequence_insert_sorted_iter() to add data to the #GSequence or, if - * you want to add a large amount of data, it is more efficient to call - * g_sequence_sort() or g_sequence_sort_iter() after doing unsorted - * insertions. - */ - - -/** - * SECTION:shell - * @title: Shell-related Utilities - * @short_description: shell-like commandline handling - * - * GLib provides the functions g_shell_quote() and g_shell_unquote() - * to handle shell-like quoting in strings. The function g_shell_parse_argv() - * parses a string similar to the way a POSIX shell (/bin/sh) would. - * - * Note that string handling in shells has many obscure and historical - * corner-cases which these functions do not necessarily reproduce. They - * are good enough in practice, though. - */ - - -/** - * SECTION:spawn - * @Short_description: process launching - * @Title: Spawning Processes - * - * GLib supports spawning of processes with an API that is more - * convenient than the bare UNIX fork() and exec(). - * - * The g_spawn family of functions has synchronous (g_spawn_sync()) - * and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()), - * as well as convenience variants that take a complete shell-like - * commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()). - * - * See #GSubprocess in GIO for a higher-level API that provides - * stream interfaces for communication with child processes. - * - * An example of using g_spawn_async_with_pipes(): - * |[ - * const gchar * const argv[] = { "my-favourite-program", "--args", NULL }; - * gint child_stdout, child_stderr; - * GPid child_pid; - * g_autoptr(GError) error = NULL; - * - * // Spawn child process. - * g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL, - * NULL, &child_pid, NULL, &child_stdout, - * &child_stderr, &error); - * if (error != NULL) - * { - * g_error ("Spawning child failed: %s", error->message); - * return; - * } - * - * // Add a child watch function which will be called when the child process - * // exits. - * g_child_watch_add (child_pid, child_watch_cb, NULL); - * - * // You could watch for output on @child_stdout and @child_stderr using - * // #GUnixInputStream or #GIOChannel here. - * - * static void - * child_watch_cb (GPid pid, - * gint status, - * gpointer user_data) - * { - * g_message ("Child %" G_PID_FORMAT " exited %s", pid, - * g_spawn_check_wait_status (status, NULL) ? "normally" : "abnormally"); - * - * // Free any resources associated with the child here, such as I/O channels - * // on its stdout and stderr FDs. If you have no code to put in the - * // child_watch_cb() callback, you can remove it and the g_child_watch_add() - * // call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag, - * // otherwise the child process will stay around as a zombie until this - * // process exits. - * - * g_spawn_close_pid (pid); - * } - * ]| - */ - - -/** - * SECTION:string_chunks - * @title: String Chunks - * @short_description: efficient storage of groups of strings - * - * String chunks are used to store groups of strings. Memory is - * allocated in blocks, and as strings are added to the #GStringChunk - * they are copied into the next free position in a block. When a block - * is full a new block is allocated. - * - * When storing a large number of strings, string chunks are more - * efficient than using g_strdup() since fewer calls to malloc() are - * needed, and less memory is wasted in memory allocation overheads. - * - * By adding strings with g_string_chunk_insert_const() it is also - * possible to remove duplicates. - * - * To create a new #GStringChunk use g_string_chunk_new(). - * - * To add strings to a #GStringChunk use g_string_chunk_insert(). - * - * To add strings to a #GStringChunk, but without duplicating strings - * which are already in the #GStringChunk, use - * g_string_chunk_insert_const(). - * - * To free the entire #GStringChunk use g_string_chunk_free(). It is - * not possible to free individual strings. - */ - - -/** - * SECTION:string_utils - * @title: String Utility Functions - * @short_description: various string-related functions - * - * This section describes a number of utility functions for creating, - * duplicating, and manipulating strings. - * - * Note that the functions g_printf(), g_fprintf(), g_sprintf(), - * g_vprintf(), g_vfprintf(), g_vsprintf() and g_vasprintf() - * are declared in the header `gprintf.h` which is not included in `glib.h` - * (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to - * explicitly include `` in order to use the GLib - * printf() functions. - * - * ## String precision pitfalls # {#string-precision} - * - * While you may use the printf() functions to format UTF-8 strings, - * notice that the precision of a \%Ns parameter is interpreted - * as the number of bytes, not characters to print. On top of that, - * the GNU libc implementation of the printf() functions has the - * "feature" that it checks that the string given for the \%Ns - * parameter consists of a whole number of characters in the current - * encoding. So, unless you are sure you are always going to be in an - * UTF-8 locale or your know your text is restricted to ASCII, avoid - * using \%Ns. If your intention is to format strings for a - * certain number of columns, then \%Ns is not a correct solution - * anyway, since it fails to take wide characters (see g_unichar_iswide()) - * into account. - * - * Note also that there are various printf() parameters which are platform - * dependent. GLib provides platform independent macros for these parameters - * which should be used instead. A common example is %G_GUINT64_FORMAT, which - * should be used instead of `%llu` or similar parameters for formatting - * 64-bit integers. These macros are all named `G_*_FORMAT`; see - * [Basic Types][glib-Basic-Types]. - */ - - -/** - * SECTION:strings - * @title: Strings - * @short_description: text buffers which grow automatically - * as text is added - * - * A #GString is an object that handles the memory management of a C - * string for you. The emphasis of #GString is on text, typically - * UTF-8. Crucially, the "str" member of a #GString is guaranteed to - * have a trailing nul character, and it is therefore always safe to - * call functions such as strchr() or g_strdup() on it. - * - * However, a #GString can also hold arbitrary binary data, because it - * has a "len" member, which includes any possible embedded nul - * characters in the data. Conceptually then, #GString is like a - * #GByteArray with the addition of many convenience methods for text, - * and a guaranteed nul terminator. - */ - - -/** - * SECTION:testing - * @title: Testing - * @short_description: a test framework - * - * GLib provides a framework for writing and maintaining unit tests - * in parallel to the code they are testing. The API is designed according - * to established concepts found in the other test frameworks (JUnit, NUnit, - * RUnit), which in turn is based on smalltalk unit testing concepts. - * - * - Test case: Tests (test methods) are grouped together with their - * fixture into test cases. - * - * - Fixture: A test fixture consists of fixture data and setup and - * teardown methods to establish the environment for the test - * functions. We use fresh fixtures, i.e. fixtures are newly set - * up and torn down around each test invocation to avoid dependencies - * between tests. - * - * - Test suite: Test cases can be grouped into test suites, to allow - * subsets of the available tests to be run. Test suites can be - * grouped into other test suites as well. - * - * The API is designed to handle creation and registration of test suites - * and test cases implicitly. A simple call like - * |[ - * g_test_add_func ("/misc/assertions", test_assertions); - * ]| - * creates a test suite called "misc" with a single test case named - * "assertions", which consists of running the test_assertions function. - * - * In addition to the traditional g_assert_true(), the test framework provides - * an extended set of assertions for comparisons: g_assert_cmpfloat(), - * g_assert_cmpfloat_with_epsilon(), g_assert_cmpint(), g_assert_cmpuint(), - * g_assert_cmphex(), g_assert_cmpstr(), g_assert_cmpmem() and - * g_assert_cmpvariant(). The - * advantage of these variants over plain g_assert_true() is that the assertion - * messages can be more elaborate, and include the values of the compared - * entities. - * - * Note that g_assert() should not be used in unit tests, since it is a no-op - * when compiling with `G_DISABLE_ASSERT`. Use g_assert() in production code, - * and g_assert_true() in unit tests. - * - * A full example of creating a test suite with two tests using fixtures: - * |[ - * #include - * #include - * - * typedef struct { - * MyObject *obj; - * OtherObject *helper; - * } MyObjectFixture; - * - * static void - * my_object_fixture_set_up (MyObjectFixture *fixture, - * gconstpointer user_data) - * { - * fixture->obj = my_object_new (); - * my_object_set_prop1 (fixture->obj, "some-value"); - * my_object_do_some_complex_setup (fixture->obj, user_data); - * - * fixture->helper = other_object_new (); - * } - * - * static void - * my_object_fixture_tear_down (MyObjectFixture *fixture, - * gconstpointer user_data) - * { - * g_clear_object (&fixture->helper); - * g_clear_object (&fixture->obj); - * } - * - * static void - * test_my_object_test1 (MyObjectFixture *fixture, - * gconstpointer user_data) - * { - * g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "initial-value"); - * } - * - * static void - * test_my_object_test2 (MyObjectFixture *fixture, - * gconstpointer user_data) - * { - * my_object_do_some_work_using_helper (fixture->obj, fixture->helper); - * g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "updated-value"); - * } - * - * int - * main (int argc, char *argv[]) - * { - * setlocale (LC_ALL, ""); - * - * g_test_init (&argc, &argv, NULL); - * - * // Define the tests. - * g_test_add ("/my-object/test1", MyObjectFixture, "some-user-data", - * my_object_fixture_set_up, test_my_object_test1, - * my_object_fixture_tear_down); - * g_test_add ("/my-object/test2", MyObjectFixture, "some-user-data", - * my_object_fixture_set_up, test_my_object_test2, - * my_object_fixture_tear_down); - * - * return g_test_run (); - * } - * ]| - * - * ### Integrating GTest in your project - * - * If you are using the [Meson](http://mesonbuild.com) build system, you will - * typically use the provided `test()` primitive to call the test binaries, - * e.g.: - * - * |[ - * test( - * 'foo', - * executable('foo', 'foo.c', dependencies: deps), - * env: [ - * 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), - * 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), - * ], - * ) - * - * test( - * 'bar', - * executable('bar', 'bar.c', dependencies: deps), - * env: [ - * 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), - * 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), - * ], - * ) - * ]| - * - * If you are using Autotools, you're strongly encouraged to use the Automake - * [TAP](https://testanything.org/) harness; GLib provides template files for - * easily integrating with it: - * - * - [glib-tap.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib-tap.mk) - * - [tap-test](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-test) - * - [tap-driver.sh](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-driver.sh) - * - * You can copy these files in your own project's root directory, and then - * set up your `Makefile.am` file to reference them, for instance: - * - * |[ - * include $(top_srcdir)/glib-tap.mk - * - * # test binaries - * test_programs = \ - * foo \ - * bar - * - * # data distributed in the tarball - * dist_test_data = \ - * foo.data.txt \ - * bar.data.txt - * - * # data not distributed in the tarball - * test_data = \ - * blah.data.txt - * ]| - * - * Make sure to distribute the TAP files, using something like the following - * in your top-level `Makefile.am`: - * - * |[ - * EXTRA_DIST += \ - * tap-driver.sh \ - * tap-test - * ]| - * - * `glib-tap.mk` will be distributed implicitly due to being included in a - * `Makefile.am`. All three files should be added to version control. - * - * If you don't have access to the Autotools TAP harness, you can use the - * [gtester][gtester] and [gtester-report][gtester-report] tools, and use - * the [glib.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib.mk) - * Automake template provided by GLib. Note, however, that since GLib 2.62, - * [gtester][gtester] and [gtester-report][gtester-report] have been deprecated - * in favour of using TAP. The `--tap` argument to tests is enabled by default - * as of GLib 2.62. - */ - - -/** - * SECTION:thread_pools - * @title: Thread Pools - * @short_description: pools of threads to execute work concurrently - * @see_also: #GThread - * - * Sometimes you wish to asynchronously fork out the execution of work - * and continue working in your own thread. If that will happen often, - * the overhead of starting and destroying a thread each time might be - * too high. In such cases reusing already started threads seems like a - * good idea. And it indeed is, but implementing this can be tedious - * and error-prone. - * - * Therefore GLib provides thread pools for your convenience. An added - * advantage is, that the threads can be shared between the different - * subsystems of your program, when they are using GLib. - * - * To create a new thread pool, you use g_thread_pool_new(). - * It is destroyed by g_thread_pool_free(). - * - * If you want to execute a certain task within a thread pool, - * you call g_thread_pool_push(). - * - * To get the current number of running threads you call - * g_thread_pool_get_num_threads(). To get the number of still - * unprocessed tasks you call g_thread_pool_unprocessed(). To control - * the maximal number of threads for a thread pool, you use - * g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads(). - * - * Finally you can control the number of unused threads, that are kept - * alive by GLib for future use. The current number can be fetched with - * g_thread_pool_get_num_unused_threads(). The maximal number can be - * controlled by g_thread_pool_get_max_unused_threads() and - * g_thread_pool_set_max_unused_threads(). All currently unused threads - * can be stopped by calling g_thread_pool_stop_unused_threads(). - */ - - -/** - * SECTION:threads - * @title: Threads - * @short_description: portable support for threads, mutexes, locks, - * conditions and thread private data - * @see_also: #GThreadPool, #GAsyncQueue - * - * Threads act almost like processes, but unlike processes all threads - * of one process share the same memory. This is good, as it provides - * easy communication between the involved threads via this shared - * memory, and it is bad, because strange things (so called - * "Heisenbugs") might happen if the program is not carefully designed. - * In particular, due to the concurrent nature of threads, no - * assumptions on the order of execution of code running in different - * threads can be made, unless order is explicitly forced by the - * programmer through synchronization primitives. - * - * The aim of the thread-related functions in GLib is to provide a - * portable means for writing multi-threaded software. There are - * primitives for mutexes to protect the access to portions of memory - * (#GMutex, #GRecMutex and #GRWLock). There is a facility to use - * individual bits for locks (g_bit_lock()). There are primitives - * for condition variables to allow synchronization of threads (#GCond). - * There are primitives for thread-private data - data that every - * thread has a private instance of (#GPrivate). There are facilities - * for one-time initialization (#GOnce, g_once_init_enter()). Finally, - * there are primitives to create and manage threads (#GThread). - * - * The GLib threading system used to be initialized with g_thread_init(). - * This is no longer necessary. Since version 2.32, the GLib threading - * system is automatically initialized at the start of your program, - * and all thread-creation functions and synchronization primitives - * are available right away. - * - * Note that it is not safe to assume that your program has no threads - * even if you don't call g_thread_new() yourself. GLib and GIO can - * and will create threads for their own purposes in some cases, such - * as when using g_unix_signal_source_new() or when using GDBus. - * - * Originally, UNIX did not have threads, and therefore some traditional - * UNIX APIs are problematic in threaded programs. Some notable examples - * are - * - * - C library functions that return data in statically allocated - * buffers, such as strtok() or strerror(). For many of these, - * there are thread-safe variants with a _r suffix, or you can - * look at corresponding GLib APIs (like g_strsplit() or g_strerror()). - * - * - The functions setenv() and unsetenv() manipulate the process - * environment in a not thread-safe way, and may interfere with getenv() - * calls in other threads. Note that getenv() calls may be hidden behind - * other APIs. For example, GNU gettext() calls getenv() under the - * covers. In general, it is best to treat the environment as readonly. - * If you absolutely have to modify the environment, do it early in - * main(), when no other threads are around yet. - * - * - The setlocale() function changes the locale for the entire process, - * affecting all threads. Temporary changes to the locale are often made - * to change the behavior of string scanning or formatting functions - * like scanf() or printf(). GLib offers a number of string APIs - * (like g_ascii_formatd() or g_ascii_strtod()) that can often be - * used as an alternative. Or you can use the uselocale() function - * to change the locale only for the current thread. - * - * - The fork() function only takes the calling thread into the child's - * copy of the process image. If other threads were executing in critical - * sections they could have left mutexes locked which could easily - * cause deadlocks in the new child. For this reason, you should - * call exit() or exec() as soon as possible in the child and only - * make signal-safe library calls before that. - * - * - The daemon() function uses fork() in a way contrary to what is - * described above. It should not be used with GLib programs. - * - * GLib itself is internally completely thread-safe (all global data is - * automatically locked), but individual data structure instances are - * not automatically locked for performance reasons. For example, - * you must coordinate accesses to the same #GHashTable from multiple - * threads. The two notable exceptions from this rule are #GMainLoop - * and #GAsyncQueue, which are thread-safe and need no further - * application-level locking to be accessed from multiple threads. - * Most refcounting functions such as g_object_ref() are also thread-safe. - * - * A common use for #GThreads is to move a long-running blocking operation out - * of the main thread and into a worker thread. For GLib functions, such as - * single GIO operations, this is not necessary, and complicates the code. - * Instead, the `…_async()` version of the function should be used from the main - * thread, eliminating the need for locking and synchronisation between multiple - * threads. If an operation does need to be moved to a worker thread, consider - * using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a - * better choice than #GThread, as it handles thread reuse and task queueing; - * #GTask uses this internally. - * - * However, if multiple blocking operations need to be performed in sequence, - * and it is not possible to use #GTask for them, moving them to a worker thread - * can clarify the code. - */ - - -/** - * SECTION:timers - * @title: Timers - * @short_description: keep track of elapsed time - * - * #GTimer records a start time, and counts microseconds elapsed since - * that time. This is done somewhat differently on different platforms, - * and can be tricky to get exactly right, so #GTimer provides a - * portable/convenient interface. - */ - - -/** - * SECTION:timezone - * @title: GTimeZone - * @short_description: a structure representing a time zone - * @see_also: #GDateTime - * - * #GTimeZone is a structure that represents a time zone, at no - * particular point in time. It is refcounted and immutable. - * - * Each time zone has an identifier (for example, ‘Europe/London’) which is - * platform dependent. See g_time_zone_new() for information on the identifier - * formats. The identifier of a time zone can be retrieved using - * g_time_zone_get_identifier(). - * - * A time zone contains a number of intervals. Each interval has - * an abbreviation to describe it (for example, ‘PDT’), an offset to UTC and a - * flag indicating if the daylight savings time is in effect during that - * interval. A time zone always has at least one interval — interval 0. Note - * that interval abbreviations are not the same as time zone identifiers - * (apart from ‘UTC’), and cannot be passed to g_time_zone_new(). - * - * Every UTC time is contained within exactly one interval, but a given - * local time may be contained within zero, one or two intervals (due to - * incontinuities associated with daylight savings time). - * - * An interval may refer to a specific period of time (eg: the duration - * of daylight savings time during 2010) or it may refer to many periods - * of time that share the same properties (eg: all periods of daylight - * savings time). It is also possible (usually for political reasons) - * that some properties (like the abbreviation) change between intervals - * without other properties changing. - * - * #GTimeZone is available since GLib 2.26. - */ - - -/** - * SECTION:trash_stack - * @title: Trash Stacks - * @short_description: maintain a stack of unused allocated memory chunks - * - * A #GTrashStack is an efficient way to keep a stack of unused allocated - * memory chunks. Each memory chunk is required to be large enough to hold - * a #gpointer. This allows the stack to be maintained without any space - * overhead, since the stack pointers can be stored inside the memory chunks. - * - * There is no function to create a #GTrashStack. A %NULL #GTrashStack* - * is a perfectly valid empty stack. - * - * There is no longer any good reason to use #GTrashStack. If you have - * extra pieces of memory, free() them and allocate them again later. - * - * Deprecated: 2.48: #GTrashStack is deprecated without replacement - */ - - -/** - * SECTION:trees-binary - * @title: Balanced Binary Trees - * @short_description: a sorted collection of key/value pairs optimized - * for searching and traversing in order - * - * The #GTree structure and its associated functions provide a sorted - * collection of key/value pairs optimized for searching and traversing - * in order. This means that most of the operations (access, search, - * insertion, deletion, ...) on #GTree are O(log(n)) in average and O(n) - * in worst case for time complexity. But, note that maintaining a - * balanced sorted #GTree of n elements is done in time O(n log(n)). - * - * To create a new #GTree use g_tree_new(). - * - * To insert a key/value pair into a #GTree use g_tree_insert() - * (O(n log(n))). - * - * To remove a key/value pair use g_tree_remove() (O(n log(n))). - * - * To look up the value corresponding to a given key, use - * g_tree_lookup() and g_tree_lookup_extended(). - * - * To find out the number of nodes in a #GTree, use g_tree_nnodes(). To - * get the height of a #GTree, use g_tree_height(). - * - * To traverse a #GTree, calling a function for each node visited in - * the traversal, use g_tree_foreach(). - * - * To destroy a #GTree, use g_tree_destroy(). - */ - - -/** - * SECTION:trees-nary - * @title: N-ary Trees - * @short_description: trees of data with any number of branches - * - * The #GNode struct and its associated functions provide a N-ary tree - * data structure, where nodes in the tree can contain arbitrary data. - * - * To create a new tree use g_node_new(). - * - * To insert a node into a tree use g_node_insert(), - * g_node_insert_before(), g_node_append() and g_node_prepend(). - * - * To create a new node and insert it into a tree use - * g_node_insert_data(), g_node_insert_data_after(), - * g_node_insert_data_before(), g_node_append_data() - * and g_node_prepend_data(). - * - * To reverse the children of a node use g_node_reverse_children(). - * - * To find a node use g_node_get_root(), g_node_find(), - * g_node_find_child(), g_node_child_index(), g_node_child_position(), - * g_node_first_child(), g_node_last_child(), g_node_nth_child(), - * g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling() - * or g_node_last_sibling(). - * - * To get information about a node or tree use G_NODE_IS_LEAF(), - * G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), - * g_node_n_children(), g_node_is_ancestor() or g_node_max_height(). - * - * To traverse a tree, calling a function for each node visited in the - * traversal, use g_node_traverse() or g_node_children_foreach(). - * - * To remove a node or subtree from a tree use g_node_unlink() or - * g_node_destroy(). - */ - - -/** - * SECTION:type_conversion - * @title: Type Conversion Macros - * @short_description: portably storing integers in pointer variables - * - * Many times GLib, GTK+, and other libraries allow you to pass "user - * data" to a callback, in the form of a void pointer. From time to time - * you want to pass an integer instead of a pointer. You could allocate - * an integer, with something like: - * |[ - * int *ip = g_new (int, 1); - * *ip = 42; - * ]| - * But this is inconvenient, and it's annoying to have to free the - * memory at some later time. - * - * Pointers are always at least 32 bits in size (on all platforms GLib - * intends to support). Thus you can store at least 32-bit integer values - * in a pointer value. Naively, you might try this, but it's incorrect: - * |[ - * gpointer p; - * int i; - * p = (void*) 42; - * i = (int) p; - * ]| - * Again, that example was not correct, don't copy it. - * The problem is that on some systems you need to do this: - * |[ - * gpointer p; - * int i; - * p = (void*) (long) 42; - * i = (int) (long) p; - * ]| - * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care - * to do the right thing on every platform. - * - * Warning: You may not store pointers in integers. This is not - * portable in any way, shape or form. These macros only allow storing - * integers in pointers, and only preserve 32 bits of the integer; values - * outside the range of a 32-bit integer will be mangled. - */ - - -/** - * SECTION:types - * @title: Basic Types - * @short_description: standard GLib types, defined for ease-of-use - * and portability - * - * GLib defines a number of commonly used types, which can be divided - * into several groups: - * - New types which are not part of standard C (but are defined in - * various C standard library header files) — #gboolean, #gssize. - * - Integer types which are guaranteed to be the same size across - * all platforms — #gint8, #guint8, #gint16, #guint16, #gint32, - * #guint32, #gint64, #guint64. - * - Types which are easier to use than their standard C counterparts - - * #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong. - * - Types which correspond exactly to standard C types, but are - * included for completeness — #gchar, #gint, #gshort, #glong, - * #gfloat, #gdouble. - * - Types which correspond exactly to standard C99 types, but are available - * to use even if your compiler does not support C99 — #gsize, #goffset, - * #gintptr, #guintptr. - * - * GLib also defines macros for the limits of some of the standard - * integer and floating point types, as well as macros for suitable - * printf() formats for these types. - * - * Note that depending on the platform and build configuration, the format - * macros might not be compatible with the system provided printf() function, - * because GLib might use a different printf() implementation internally. - * The format macros will always work with GLib API (like g_print()), and with - * any C99 compatible printf() implementation. - */ - - -/** - * SECTION:unicode - * @Title: Unicode Manipulation - * @Short_description: functions operating on Unicode characters and - * UTF-8 strings - * @See_also: g_locale_to_utf8(), g_locale_from_utf8() - * - * This section describes a number of functions for dealing with - * Unicode characters and strings. There are analogues of the - * traditional `ctype.h` character classification and case conversion - * functions, UTF-8 analogues of some string utility functions, - * functions to perform normalization, case conversion and collation - * on UTF-8 strings and finally functions to convert between the UTF-8, - * UTF-16 and UCS-4 encodings of Unicode. - * - * The implementations of the Unicode functions in GLib are based - * on the Unicode Character Data tables, which are available from - * [www.unicode.org](http://www.unicode.org/). - * - * * Unicode 4.0 was added in GLib 2.8 - * * Unicode 4.1 was added in GLib 2.10 - * * Unicode 5.0 was added in GLib 2.12 - * * Unicode 5.1 was added in GLib 2.16.3 - * * Unicode 6.0 was added in GLib 2.30 - * * Unicode 6.1 was added in GLib 2.32 - * * Unicode 6.2 was added in GLib 2.36 - * * Unicode 6.3 was added in GLib 2.40 - * * Unicode 7.0 was added in GLib 2.42 - * * Unicode 8.0 was added in GLib 2.48 - * * Unicode 9.0 was added in GLib 2.50.1 - * * Unicode 10.0 was added in GLib 2.54 - * * Unicode 11.10 was added in GLib 2.58 - * * Unicode 12.0 was added in GLib 2.62 - * * Unicode 12.1 was added in GLib 2.62 - * * Unicode 13.0 was added in GLib 2.66 - */ - - -/** - * SECTION:uuid - * @title: GUuid - * @short_description: a universally unique identifier - * - * A UUID, or Universally unique identifier, is intended to uniquely - * identify information in a distributed environment. For the - * definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html). - * - * The creation of UUIDs does not require a centralized authority. - * - * UUIDs are of relatively small size (128 bits, or 16 bytes). The - * common string representation (ex: - * 1d6c0810-2bd6-45f3-9890-0268422a6f14) needs 37 bytes. - * - * The UUID specification defines 5 versions, and calling - * g_uuid_string_random() will generate a unique (or rather random) - * UUID of the most common version, version 4. - * - * Since: 2.52 - */ - - -/** - * SECTION:version - * @Title: Version Information - * @Short_description: variables and functions to check the GLib version - * - * GLib provides version information, primarily useful in configure - * checks for builds that have a configure script. Applications will - * not typically use the features described here. - * - * The GLib headers annotate deprecated APIs in a way that produces - * compiler warnings if these deprecated APIs are used. The warnings - * can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS - * before including the glib.h header. - * - * GLib also provides support for building applications against - * defined subsets of deprecated or new GLib APIs. Define the macro - * %GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib - * you want to receive warnings about deprecated APIs. Define the - * macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of - * GLib whose API you want to use. - */ - - -/** - * SECTION:warnings - * @title: Warnings and Assertions - * @short_description: warnings and assertions to use in runtime code - * - * GLib defines several warning functions and assertions which can be used to - * warn of programmer errors when calling functions, and print error messages - * from command line programs. - * - * The g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and - * g_return_val_if_reached() macros are intended as pre-condition assertions, to - * be used at the top of a public function to check that the function’s - * arguments are acceptable. Any failure of such a pre-condition assertion is - * considered a programming error on the part of the caller of the public API, - * and the program is considered to be in an undefined state afterwards. They - * are similar to the libc assert() function, but provide more context on - * failures. - * - * For example: - * |[ - * gboolean - * g_dtls_connection_shutdown (GDtlsConnection *conn, - * gboolean shutdown_read, - * gboolean shutdown_write, - * GCancellable *cancellable, - * GError **error) - * { - * // local variable declarations - * - * g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE); - * g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE); - * g_return_val_if_fail (error == NULL || *error == NULL, FALSE); - * - * // function body - * - * return return_val; - * } - * ]| - * - * g_print(), g_printerr() and g_set_print_handler() are intended to be used for - * output from command line applications, since they output to standard output - * and standard error by default — whereas functions like g_message() and - * g_log() may be redirected to special purpose message windows, files, or the - * system journal. - */ - - -/** - * SECTION:windows - * @title: Windows Compatibility Functions - * @short_description: UNIX emulation on Windows - * - * These functions provide some level of UNIX emulation on the - * Windows platform. If your application really needs the POSIX - * APIs, we suggest you try the Cygwin project. - */ - - -/** - * TRUE: - * - * Defines the %TRUE value for the #gboolean type. - */ - - -/** - * _: - * @String: the string to be translated - * - * Marks a string for translation, gets replaced with the translated string - * at runtime. - * - * Since: 2.4 - */ - - -/** - * _glib_get_locale_dir: - * - * Return the path to the share\locale or lib\locale subfolder of the - * GLib installation folder. The path is in the system codepage. We - * have to use system codepage as bindtextdomain() doesn't have a - * UTF-8 interface. - */ - - -/** - * g_abort: - * - * A wrapper for the POSIX abort() function. - * - * On Windows it is a function that makes extra effort (including a call - * to abort()) to ensure that a debugger-catchable exception is thrown - * before the program terminates. - * - * See your C library manual for more details about abort(). - * - * Since: 2.50 - */ - - -/** - * g_access: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * @mode: as in access() - * - * A wrapper for the POSIX access() function. This function is used to - * test a pathname for one or several of read, write or execute - * permissions, or just existence. - * - * On Windows, the file protection mechanism is not at all POSIX-like, - * and the underlying function in the C library only checks the - * FAT-style READONLY attribute, and does not look at the ACL of a - * file at all. This function is this in practise almost useless on - * Windows. Software that needs to handle file permissions on Windows - * more exactly should use the Win32 API. - * - * See your C library manual for more details about access(). - * - * Returns: zero if the pathname refers to an existing file system - * object that has all the tested permissions, or -1 otherwise - * or on error. - * Since: 2.8 - */ - - -/** - * g_array_append_val: - * @a: a #GArray - * @v: the value to append to the #GArray - * - * Adds the value on to the end of the array. The array will grow in - * size automatically if necessary. - * - * g_array_append_val() is a macro which uses a reference to the value - * parameter @v. This means that you cannot use it with literal values - * such as "27". You must use variables. - * - * Returns: the #GArray - */ - - -/** - * g_array_append_vals: - * @array: a #GArray - * @data: (not nullable): a pointer to the elements to append to the end of the array - * @len: the number of elements to append - * - * Adds @len elements onto the end of the array. - * - * Returns: the #GArray - */ - - -/** - * g_array_binary_search: - * @array: a #GArray. - * @target: a pointer to the item to look up. - * @compare_func: A #GCompareFunc used to locate @target. - * @out_match_index: (optional) (out): return location - * for the index of the element, if found. - * - * Checks whether @target exists in @array by performing a binary - * search based on the given comparison function @compare_func which - * get pointers to items as arguments. If the element is found, %TRUE - * is returned and the element’s index is returned in @out_match_index - * (if non-%NULL). Otherwise, %FALSE is returned and @out_match_index - * is undefined. If @target exists multiple times in @array, the index - * of the first instance is returned. This search is using a binary - * search, so the @array must absolutely be sorted to return a correct - * result (if not, the function may produce false-negative). - * - * This example defines a comparison function and search an element in a #GArray: - * |[ - * static gint* - * cmpint (gconstpointer a, gconstpointer b) - * { - * const gint *_a = a; - * const gint *_b = b; - * - * return *_a - *_b; - * } - * ... - * gint i = 424242; - * guint matched_index; - * gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_index); - * ... - * ]| - * - * Returns: %TRUE if @target is one of the elements of @array, %FALSE otherwise. - * Since: 2.62 - */ - - -/** - * g_array_copy: - * @array: A #GArray. - * - * Create a shallow copy of a #GArray. If the array elements consist of - * pointers to data, the pointers are copied but the actual data is not. - * - * Returns: (transfer container): A copy of @array. - * Since: 2.62 - */ - - -/** - * g_array_free: - * @array: a #GArray - * @free_segment: if %TRUE the actual element data is freed as well - * - * Frees the memory allocated for the #GArray. If @free_segment is - * %TRUE it frees the memory block holding the elements as well. Pass - * %FALSE if you want to free the #GArray wrapper but preserve the - * underlying array for use elsewhere. If the reference count of - * @array is greater than one, the #GArray wrapper is preserved but - * the size of @array will be set to zero. - * - * If array contents point to dynamically-allocated memory, they should - * be freed separately if @free_seg is %TRUE and no @clear_func - * function has been set for @array. - * - * This function is not thread-safe. If using a #GArray from multiple - * threads, use only the atomic g_array_ref() and g_array_unref() - * functions. - * - * Returns: the element data if @free_segment is %FALSE, otherwise - * %NULL. The element data should be freed using g_free(). - */ - - -/** - * g_array_get_element_size: - * @array: A #GArray - * - * Gets the size of the elements in @array. - * - * Returns: Size of each element, in bytes - * Since: 2.22 - */ - - -/** - * g_array_index: - * @a: a #GArray - * @t: the type of the elements - * @i: the index of the element to return - * - * Returns the element of a #GArray at the given index. The return - * value is cast to the given type. This is the main way to read or write an - * element in a #GArray. - * - * Writing an element is typically done by reference, as in the following - * example. This example gets a pointer to an element in a #GArray, and then - * writes to a field in it: - * |[ - * EDayViewEvent *event; - * // This gets a pointer to the 4th element in the array of - * // EDayViewEvent structs. - * event = &g_array_index (events, EDayViewEvent, 3); - * event->start_time = g_get_current_time (); - * ]| - * - * This example reads from and writes to an array of integers: - * |[ - * g_autoptr(GArray) int_array = g_array_new (FALSE, FALSE, sizeof (guint)); - * for (guint i = 0; i < 10; i++) - * g_array_append_val (int_array, i); - * - * guint *my_int = &g_array_index (int_array, guint, 1); - * g_print ("Int at index 1 is %u; decrementing it\n", *my_int); - * *my_int = *my_int - 1; - * ]| - * - * Returns: the element of the #GArray at the index given by @i - */ - - -/** - * g_array_insert_val: - * @a: a #GArray - * @i: the index to place the element at - * @v: the value to insert into the array - * - * Inserts an element into an array at the given index. - * - * g_array_insert_val() is a macro which uses a reference to the value - * parameter @v. This means that you cannot use it with literal values - * such as "27". You must use variables. - * - * Returns: the #GArray - */ - - -/** - * g_array_insert_vals: - * @array: a #GArray - * @index_: the index to place the elements at - * @data: (nullable): a pointer to the elements to insert - * @len: the number of elements to insert - * - * Inserts @len elements into a #GArray at the given index. - * - * If @index_ is greater than the array’s current length, the array is expanded. - * The elements between the old end of the array and the newly inserted elements - * will be initialised to zero if the array was configured to clear elements; - * otherwise their values will be undefined. - * - * If @index_ is less than the array’s current length, new entries will be - * inserted into the array, and the existing entries above @index_ will be moved - * upwards. - * - * @data may be %NULL if (and only if) @len is zero. If @len is zero, this - * function is a no-op. - * - * Returns: the #GArray - */ - - -/** - * g_array_new: - * @zero_terminated: %TRUE if the array should have an extra element at - * the end which is set to 0 - * @clear_: %TRUE if #GArray elements should be automatically cleared - * to 0 when they are allocated - * @element_size: the size of each element in bytes - * - * Creates a new #GArray with a reference count of 1. - * - * Returns: the new #GArray - */ - - -/** - * g_array_prepend_val: - * @a: a #GArray - * @v: the value to prepend to the #GArray - * - * Adds the value on to the start of the array. The array will grow in - * size automatically if necessary. - * - * This operation is slower than g_array_append_val() since the - * existing elements in the array have to be moved to make space for - * the new element. - * - * g_array_prepend_val() is a macro which uses a reference to the value - * parameter @v. This means that you cannot use it with literal values - * such as "27". You must use variables. - * - * Returns: the #GArray - */ - - -/** - * g_array_prepend_vals: - * @array: a #GArray - * @data: (nullable): a pointer to the elements to prepend to the start of the array - * @len: the number of elements to prepend, which may be zero - * - * Adds @len elements onto the start of the array. - * - * @data may be %NULL if (and only if) @len is zero. If @len is zero, this - * function is a no-op. - * - * This operation is slower than g_array_append_vals() since the - * existing elements in the array have to be moved to make space for - * the new elements. - * - * Returns: the #GArray - */ - - -/** - * g_array_ref: - * @array: A #GArray - * - * Atomically increments the reference count of @array by one. - * This function is thread-safe and may be called from any thread. - * - * Returns: The passed in #GArray - * Since: 2.22 - */ - - -/** - * g_array_remove_index: - * @array: a #GArray - * @index_: the index of the element to remove - * - * Removes the element at the given index from a #GArray. The following - * elements are moved down one place. - * - * Returns: the #GArray - */ - - -/** - * g_array_remove_index_fast: - * @array: a @GArray - * @index_: the index of the element to remove - * - * Removes the element at the given index from a #GArray. The last - * element in the array is used to fill in the space, so this function - * does not preserve the order of the #GArray. But it is faster than - * g_array_remove_index(). - * - * Returns: the #GArray - */ - - -/** - * g_array_remove_range: - * @array: a @GArray - * @index_: the index of the first element to remove - * @length: the number of elements to remove - * - * Removes the given number of elements starting at the given index - * from a #GArray. The following elements are moved to close the gap. - * - * Returns: the #GArray - * Since: 2.4 - */ - - -/** - * g_array_set_clear_func: - * @array: A #GArray - * @clear_func: a function to clear an element of @array - * - * Sets a function to clear an element of @array. - * - * The @clear_func will be called when an element in the array - * data segment is removed and when the array is freed and data - * segment is deallocated as well. @clear_func will be passed a - * pointer to the element to clear, rather than the element itself. - * - * Note that in contrast with other uses of #GDestroyNotify - * functions, @clear_func is expected to clear the contents of - * the array element it is given, but not free the element itself. - * - * |[ - * typedef struct - * { - * gchar *str; - * GObject *obj; - * } ArrayElement; - * - * static void - * array_element_clear (ArrayElement *element) - * { - * g_clear_pointer (&element->str, g_free); - * g_clear_object (&element->obj); - * } - * - * // main code - * GArray *garray = g_array_new (FALSE, FALSE, sizeof (ArrayElement)); - * g_array_set_clear_func (garray, (GDestroyNotify) array_element_clear); - * // assign data to the structure - * g_array_free (garray, TRUE); - * ]| - * - * Since: 2.32 - */ - - -/** - * g_array_set_size: - * @array: a #GArray - * @length: the new size of the #GArray - * - * Sets the size of the array, expanding it if necessary. If the array - * was created with @clear_ set to %TRUE, the new elements are set to 0. - * - * Returns: the #GArray - */ - - -/** - * g_array_sized_new: - * @zero_terminated: %TRUE if the array should have an extra element at - * the end with all bits cleared - * @clear_: %TRUE if all bits in the array should be cleared to 0 on - * allocation - * @element_size: size of each element in the array - * @reserved_size: number of elements preallocated - * - * Creates a new #GArray with @reserved_size elements preallocated and - * a reference count of 1. This avoids frequent reallocation, if you - * are going to add many elements to the array. Note however that the - * size of the array is still 0. - * - * Returns: the new #GArray - */ - - -/** - * g_array_sort: - * @array: a #GArray - * @compare_func: comparison function - * - * Sorts a #GArray using @compare_func which should be a qsort()-style - * comparison function (returns less than zero for first arg is less - * than second arg, zero for equal, greater zero if first arg is - * greater than second arg). - * - * This is guaranteed to be a stable sort since version 2.32. - */ - - -/** - * g_array_sort_with_data: - * @array: a #GArray - * @compare_func: comparison function - * @user_data: data to pass to @compare_func - * - * Like g_array_sort(), but the comparison function receives an extra - * user data argument. - * - * This is guaranteed to be a stable sort since version 2.32. - * - * There used to be a comment here about making the sort stable by - * using the addresses of the elements in the comparison function. - * This did not actually work, so any such code should be removed. - */ - - -/** - * g_array_steal: - * @array: a #GArray. - * @len: (optional) (out): pointer to retrieve the number of - * elements of the original array - * - * Frees the data in the array and resets the size to zero, while - * the underlying array is preserved for use elsewhere and returned - * to the caller. - * - * If the array was created with the @zero_terminate property - * set to %TRUE, the returned data is zero terminated too. - * - * If array elements contain dynamically-allocated memory, - * the array elements should also be freed by the caller. - * - * A short example of use: - * |[ - * ... - * gpointer data; - * gsize data_len; - * data = g_array_steal (some_array, &data_len); - * ... - * ]| - * - * Returns: (transfer full): the element data, which should be - * freed using g_free(). - * Since: 2.64 - */ - - -/** - * g_array_unref: - * @array: A #GArray - * - * Atomically decrements the reference count of @array by one. If the - * reference count drops to 0, all memory allocated by the array is - * released. This function is thread-safe and may be called from any - * thread. - * - * Since: 2.22 - */ - - -/** - * g_ascii_digit_value: - * @c: an ASCII character - * - * Determines the numeric value of a character as a decimal digit. - * Differs from g_unichar_digit_value() because it takes a char, so - * there's no worry about sign extension if characters are signed. - * - * Returns: If @c is a decimal digit (according to g_ascii_isdigit()), - * its numeric value. Otherwise, -1. - */ - - -/** - * g_ascii_dtostr: - * @buffer: A buffer to place the resulting string in - * @buf_len: The length of the buffer. - * @d: The #gdouble to convert - * - * Converts a #gdouble to a string, using the '.' as - * decimal point. - * - * This function generates enough precision that converting - * the string back using g_ascii_strtod() gives the same machine-number - * (on machines with IEEE compatible 64bit doubles). It is - * guaranteed that the size of the resulting string will never - * be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating - * nul character, which is always added. - * - * Returns: The pointer to the buffer with the converted string. - */ - - -/** - * g_ascii_formatd: - * @buffer: A buffer to place the resulting string in - * @buf_len: The length of the buffer. - * @format: The printf()-style format to use for the - * code to use for converting. - * @d: The #gdouble to convert - * - * Converts a #gdouble to a string, using the '.' as - * decimal point. To format the number you pass in - * a printf()-style format string. Allowed conversion - * specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'. - * - * The returned buffer is guaranteed to be nul-terminated. - * - * If you just want to want to serialize the value into a - * string, use g_ascii_dtostr(). - * - * Returns: The pointer to the buffer with the converted string. - */ - - -/** - * g_ascii_isalnum: - * @c: any character - * - * Determines whether a character is alphanumeric. - * - * Unlike the standard C library isalnum() function, this only - * recognizes standard ASCII letters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before - * passing a possibly non-ASCII character in. - * - * Returns: %TRUE if @c is an ASCII alphanumeric character - */ - - -/** - * g_ascii_isalpha: - * @c: any character - * - * Determines whether a character is alphabetic (i.e. a letter). - * - * Unlike the standard C library isalpha() function, this only - * recognizes standard ASCII letters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before - * passing a possibly non-ASCII character in. - * - * Returns: %TRUE if @c is an ASCII alphabetic character - */ - - -/** - * g_ascii_iscntrl: - * @c: any character - * - * Determines whether a character is a control character. - * - * Unlike the standard C library iscntrl() function, this only - * recognizes standard ASCII control characters and ignores the - * locale, returning %FALSE for all non-ASCII characters. Also, - * unlike the standard library function, this takes a char, not - * an int, so don't call it on %EOF, but no need to cast to #guchar - * before passing a possibly non-ASCII character in. - * - * Returns: %TRUE if @c is an ASCII control character. - */ - - -/** - * g_ascii_isdigit: - * @c: any character - * - * Determines whether a character is digit (0-9). - * - * Unlike the standard C library isdigit() function, this takes - * a char, not an int, so don't call it on %EOF, but no need to - * cast to #guchar before passing a possibly non-ASCII character in. - * - * Returns: %TRUE if @c is an ASCII digit. - */ - - -/** - * g_ascii_isgraph: - * @c: any character - * - * Determines whether a character is a printing character and not a space. - * - * Unlike the standard C library isgraph() function, this only - * recognizes standard ASCII characters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before - * passing a possibly non-ASCII character in. - * - * Returns: %TRUE if @c is an ASCII printing character other than space. - */ - - -/** - * g_ascii_islower: - * @c: any character - * - * Determines whether a character is an ASCII lower case letter. - * - * Unlike the standard C library islower() function, this only - * recognizes standard ASCII letters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to worry about casting - * to #guchar before passing a possibly non-ASCII character in. - * - * Returns: %TRUE if @c is an ASCII lower case letter - */ - - -/** - * g_ascii_isprint: - * @c: any character - * - * Determines whether a character is a printing character. - * - * Unlike the standard C library isprint() function, this only - * recognizes standard ASCII characters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before - * passing a possibly non-ASCII character in. - * - * Returns: %TRUE if @c is an ASCII printing character. - */ - - -/** - * g_ascii_ispunct: - * @c: any character - * - * Determines whether a character is a punctuation character. - * - * Unlike the standard C library ispunct() function, this only - * recognizes standard ASCII letters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before - * passing a possibly non-ASCII character in. - * - * Returns: %TRUE if @c is an ASCII punctuation character. - */ - - -/** - * g_ascii_isspace: - * @c: any character - * - * Determines whether a character is a white-space character. - * - * Unlike the standard C library isspace() function, this only - * recognizes standard ASCII white-space and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to cast to #guchar before - * passing a possibly non-ASCII character in. - * - * Returns: %TRUE if @c is an ASCII white-space character - */ - - -/** - * g_ascii_isupper: - * @c: any character - * - * Determines whether a character is an ASCII upper case letter. - * - * Unlike the standard C library isupper() function, this only - * recognizes standard ASCII letters and ignores the locale, - * returning %FALSE for all non-ASCII characters. Also, unlike - * the standard library function, this takes a char, not an int, - * so don't call it on %EOF, but no need to worry about casting - * to #guchar before passing a possibly non-ASCII character in. - * - * Returns: %TRUE if @c is an ASCII upper case letter - */ - - -/** - * g_ascii_isxdigit: - * @c: any character - * - * Determines whether a character is a hexadecimal-digit character. - * - * Unlike the standard C library isxdigit() function, this takes - * a char, not an int, so don't call it on %EOF, but no need to - * cast to #guchar before passing a possibly non-ASCII character in. - * - * Returns: %TRUE if @c is an ASCII hexadecimal-digit character. - */ - - -/** - * g_ascii_strcasecmp: - * @s1: string to compare with @s2 - * @s2: string to compare with @s1 - * - * Compare two strings, ignoring the case of ASCII characters. - * - * Unlike the BSD strcasecmp() function, this only recognizes standard - * ASCII letters and ignores the locale, treating all non-ASCII - * bytes as if they are not letters. - * - * This function should be used only on strings that are known to be - * in encodings where the bytes corresponding to ASCII letters always - * represent themselves. This includes UTF-8 and the ISO-8859-* - * charsets, but not for instance double-byte encodings like the - * Windows Codepage 932, where the trailing bytes of double-byte - * characters include all ASCII letters. If you compare two CP932 - * strings using this function, you will get false matches. - * - * Both @s1 and @s2 must be non-%NULL. - * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. - */ - - -/** - * g_ascii_strdown: - * @str: a string - * @len: length of @str in bytes, or -1 if @str is nul-terminated - * - * Converts all upper case ASCII letters to lower case ASCII letters. - * - * Returns: a newly-allocated string, with all the upper case - * characters in @str converted to lower case, with semantics that - * exactly match g_ascii_tolower(). (Note that this is unlike the - * old g_strdown(), which modified the string in place.) - */ - - -/** - * g_ascii_string_to_signed: - * @str: a string - * @base: base of a parsed number - * @min: a lower bound (inclusive) - * @max: an upper bound (inclusive) - * @out_num: (out) (optional): a return location for a number - * @error: a return location for #GError - * - * A convenience function for converting a string to a signed number. - * - * This function assumes that @str contains only a number of the given - * @base that is within inclusive bounds limited by @min and @max. If - * this is true, then the converted number is stored in @out_num. An - * empty string is not a valid input. A string with leading or - * trailing whitespace is also an invalid input. - * - * @base can be between 2 and 36 inclusive. Hexadecimal numbers must - * not be prefixed with "0x" or "0X". Such a problem does not exist - * for octal numbers, since they were usually prefixed with a zero - * which does not change the value of the parsed number. - * - * Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR - * domain. If the input is invalid, the error code will be - * %G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of - * bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. - * - * See g_ascii_strtoll() if you have more complex needs such as - * parsing a string which starts with a number, but then has other - * characters. - * - * Returns: %TRUE if @str was a number, otherwise %FALSE. - * Since: 2.54 - */ - - -/** - * g_ascii_string_to_unsigned: - * @str: a string - * @base: base of a parsed number - * @min: a lower bound (inclusive) - * @max: an upper bound (inclusive) - * @out_num: (out) (optional): a return location for a number - * @error: a return location for #GError - * - * A convenience function for converting a string to an unsigned number. - * - * This function assumes that @str contains only a number of the given - * @base that is within inclusive bounds limited by @min and @max. If - * this is true, then the converted number is stored in @out_num. An - * empty string is not a valid input. A string with leading or - * trailing whitespace is also an invalid input. A string with a leading sign - * (`-` or `+`) is not a valid input for the unsigned parser. - * - * @base can be between 2 and 36 inclusive. Hexadecimal numbers must - * not be prefixed with "0x" or "0X". Such a problem does not exist - * for octal numbers, since they were usually prefixed with a zero - * which does not change the value of the parsed number. - * - * Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR - * domain. If the input is invalid, the error code will be - * %G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of - * bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS. - * - * See g_ascii_strtoull() if you have more complex needs such as - * parsing a string which starts with a number, but then has other - * characters. - * - * Returns: %TRUE if @str was a number, otherwise %FALSE. - * Since: 2.54 - */ - - -/** - * g_ascii_strncasecmp: - * @s1: string to compare with @s2 - * @s2: string to compare with @s1 - * @n: number of characters to compare - * - * Compare @s1 and @s2, ignoring the case of ASCII characters and any - * characters after the first @n in each string. - * - * Unlike the BSD strcasecmp() function, this only recognizes standard - * ASCII letters and ignores the locale, treating all non-ASCII - * characters as if they are not letters. - * - * The same warning as in g_ascii_strcasecmp() applies: Use this - * function only on strings known to be in encodings where bytes - * corresponding to ASCII letters always represent themselves. - * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. - */ - - -/** - * g_ascii_strtod: - * @nptr: the string to convert to a numeric value. - * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the - * character after the last character used in the conversion. - * - * Converts a string to a #gdouble value. - * - * This function behaves like the standard strtod() function - * does in the C locale. It does this without actually changing - * the current locale, since that would not be thread-safe. - * A limitation of the implementation is that this function - * will still accept localized versions of infinities and NANs. - * - * This function is typically used when reading configuration - * files or other non-user input that should be locale independent. - * To handle input from the user you should normally use the - * locale-sensitive system strtod() function. - * - * To convert from a #gdouble to a string in a locale-insensitive - * way, use g_ascii_dtostr(). - * - * If the correct value would cause overflow, plus or minus %HUGE_VAL - * is returned (according to the sign of the value), and %ERANGE is - * stored in %errno. If the correct value would cause underflow, - * zero is returned and %ERANGE is stored in %errno. - * - * This function resets %errno before calling strtod() so that - * you can reliably detect overflow and underflow. - * - * Returns: the #gdouble value. - */ - - -/** - * g_ascii_strtoll: - * @nptr: the string to convert to a numeric value. - * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the - * character after the last character used in the conversion. - * @base: to be used for the conversion, 2..36 or 0 - * - * Converts a string to a #gint64 value. - * This function behaves like the standard strtoll() function - * does in the C locale. It does this without actually - * changing the current locale, since that would not be - * thread-safe. - * - * This function is typically used when reading configuration - * files or other non-user input that should be locale independent. - * To handle input from the user you should normally use the - * locale-sensitive system strtoll() function. - * - * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64 - * is returned, and `ERANGE` is stored in `errno`. - * If the base is outside the valid range, zero is returned, and - * `EINVAL` is stored in `errno`. If the - * string conversion fails, zero is returned, and @endptr returns @nptr - * (if @endptr is non-%NULL). - * - * Returns: the #gint64 value or zero on error. - * Since: 2.12 - */ - - -/** - * g_ascii_strtoull: - * @nptr: the string to convert to a numeric value. - * @endptr: (out) (transfer none) (optional): if non-%NULL, it returns the - * character after the last character used in the conversion. - * @base: to be used for the conversion, 2..36 or 0 - * - * Converts a string to a #guint64 value. - * This function behaves like the standard strtoull() function - * does in the C locale. It does this without actually - * changing the current locale, since that would not be - * thread-safe. - * - * Note that input with a leading minus sign (`-`) is accepted, and will return - * the negation of the parsed number, unless that would overflow a #guint64. - * Critically, this means you cannot assume that a short fixed length input will - * never result in a low return value, as the input could have a leading `-`. - * - * This function is typically used when reading configuration - * files or other non-user input that should be locale independent. - * To handle input from the user you should normally use the - * locale-sensitive system strtoull() function. - * - * If the correct value would cause overflow, %G_MAXUINT64 - * is returned, and `ERANGE` is stored in `errno`. - * If the base is outside the valid range, zero is returned, and - * `EINVAL` is stored in `errno`. - * If the string conversion fails, zero is returned, and @endptr returns - * @nptr (if @endptr is non-%NULL). - * - * Returns: the #guint64 value or zero on error. - * Since: 2.2 - */ - - -/** - * g_ascii_strup: - * @str: a string - * @len: length of @str in bytes, or -1 if @str is nul-terminated - * - * Converts all lower case ASCII letters to upper case ASCII letters. - * - * Returns: a newly allocated string, with all the lower case - * characters in @str converted to upper case, with semantics that - * exactly match g_ascii_toupper(). (Note that this is unlike the - * old g_strup(), which modified the string in place.) - */ - - -/** - * g_ascii_tolower: - * @c: any character - * - * Convert a character to ASCII lower case. - * - * Unlike the standard C library tolower() function, this only - * recognizes standard ASCII letters and ignores the locale, returning - * all non-ASCII characters unchanged, even if they are lower case - * letters in a particular character set. Also unlike the standard - * library function, this takes and returns a char, not an int, so - * don't call it on %EOF but no need to worry about casting to #guchar - * before passing a possibly non-ASCII character in. - * - * Returns: the result of converting @c to lower case. If @c is - * not an ASCII upper case letter, @c is returned unchanged. - */ - - -/** - * g_ascii_toupper: - * @c: any character - * - * Convert a character to ASCII upper case. - * - * Unlike the standard C library toupper() function, this only - * recognizes standard ASCII letters and ignores the locale, returning - * all non-ASCII characters unchanged, even if they are upper case - * letters in a particular character set. Also unlike the standard - * library function, this takes and returns a char, not an int, so - * don't call it on %EOF but no need to worry about casting to #guchar - * before passing a possibly non-ASCII character in. - * - * Returns: the result of converting @c to upper case. If @c is not - * an ASCII lower case letter, @c is returned unchanged. - */ - - -/** - * g_ascii_xdigit_value: - * @c: an ASCII character. - * - * Determines the numeric value of a character as a hexadecimal - * digit. Differs from g_unichar_xdigit_value() because it takes - * a char, so there's no worry about sign extension if characters - * are signed. - * - * Returns: If @c is a hex digit (according to g_ascii_isxdigit()), - * its numeric value. Otherwise, -1. - */ - - -/** - * g_assert: - * @expr: the expression to check - * - * Debugging macro to terminate the application if the assertion - * fails. If the assertion fails (i.e. the expression is not true), - * an error message is logged and the application is terminated. - * - * The macro can be turned off in final releases of code by defining - * `G_DISABLE_ASSERT` when compiling the application, so code must - * not depend on any side effects from @expr. Similarly, it must not be used - * in unit tests, otherwise the unit tests will be ineffective if compiled with - * `G_DISABLE_ASSERT`. Use g_assert_true() and related macros in unit tests - * instead. - */ - - -/** - * g_assert_cmpfloat: - * @n1: a floating point number - * @cmp: The comparison operator to use. - * One of `==`, `!=`, `<`, `>`, `<=`, `>=`. - * @n2: another floating point number - * - * Debugging macro to compare two floating point numbers. - * - * The effect of `g_assert_cmpfloat (n1, op, n2)` is - * the same as `g_assert_true (n1 op n2)`. The advantage - * of this macro is that it can produce a message that includes the - * actual values of @n1 and @n2. - * - * Since: 2.16 - */ - - -/** - * g_assert_cmpfloat_with_epsilon: - * @n1: a floating point number - * @n2: another floating point number - * @epsilon: a numeric value that expresses the expected tolerance - * between @n1 and @n2 - * - * Debugging macro to compare two floating point numbers within an epsilon. - * - * The effect of `g_assert_cmpfloat_with_epsilon (n1, n2, epsilon)` is - * the same as `g_assert_true (abs (n1 - n2) < epsilon)`. The advantage - * of this macro is that it can produce a message that includes the - * actual values of @n1 and @n2. - * - * Since: 2.58 - */ - - -/** - * g_assert_cmphex: - * @n1: an unsigned integer - * @cmp: The comparison operator to use. - * One of `==`, `!=`, `<`, `>`, `<=`, `>=`. - * @n2: another unsigned integer - * - * Debugging macro to compare to unsigned integers. - * - * This is a variant of g_assert_cmpuint() that displays the numbers - * in hexadecimal notation in the message. - * - * Since: 2.16 - */ - - -/** - * g_assert_cmpint: - * @n1: an integer - * @cmp: The comparison operator to use. - * One of `==`, `!=`, `<`, `>`, `<=`, `>=`. - * @n2: another integer - * - * Debugging macro to compare two integers. - * - * The effect of `g_assert_cmpint (n1, op, n2)` is - * the same as `g_assert_true (n1 op n2)`. The advantage - * of this macro is that it can produce a message that includes the - * actual values of @n1 and @n2. - * - * Since: 2.16 - */ - - -/** - * g_assert_cmpmem: - * @m1: (nullable): pointer to a buffer - * @l1: length of @m1 - * @m2: (nullable): pointer to another buffer - * @l2: length of @m2 - * - * Debugging macro to compare memory regions. If the comparison fails, - * an error message is logged and the application is either terminated - * or the testcase marked as failed. - * - * The effect of `g_assert_cmpmem (m1, l1, m2, l2)` is - * the same as `g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0)`. - * The advantage of this macro is that it can produce a message that - * includes the actual values of @l1 and @l2. - * - * @m1 may be %NULL if (and only if) @l1 is zero; similarly for @m2 and @l2. - * - * |[ - * g_assert_cmpmem (buf->data, buf->len, expected, sizeof (expected)); - * ]| - * - * Since: 2.46 - */ - - -/** - * g_assert_cmpstr: - * @s1: a string (may be %NULL) - * @cmp: The comparison operator to use. - * One of `==`, `!=`, `<`, `>`, `<=`, `>=`. - * @s2: another string (may be %NULL) - * - * Debugging macro to compare two strings. If the comparison fails, - * an error message is logged and the application is either terminated - * or the testcase marked as failed. - * The strings are compared using g_strcmp0(). - * - * The effect of `g_assert_cmpstr (s1, op, s2)` is - * the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`. - * The advantage of this macro is that it can produce a message that - * includes the actual values of @s1 and @s2. - * - * |[ - * g_assert_cmpstr (mystring, ==, "fubar"); - * ]| - * - * Since: 2.16 - */ - - -/** - * g_assert_cmpstrv: - * @strv1: (nullable): a string array (may be %NULL) - * @strv2: (nullable): another string array (may be %NULL) - * - * Debugging macro to check if two %NULL-terminated string arrays (i.e. 2 - * #GStrv) are equal. If they are not equal, an error message is logged and the - * application is either terminated or the testcase marked as failed. - * If both arrays are %NULL, the check passes. If one array is %NULL but the - * other is not, an error message is logged. - * - * The effect of `g_assert_cmpstrv (strv1, strv2)` is the same as - * `g_assert_true (g_strv_equal (strv1, strv2))` (if both arrays are not - * %NULL). The advantage of this macro is that it can produce a message that - * includes how @strv1 and @strv2 are different. - * - * |[ - * const char *expected[] = { "one", "two", "three", NULL }; - * g_assert_cmpstrv (mystrv, expected); - * ]| - * - * Since: 2.68 - */ - - -/** - * g_assert_cmpuint: - * @n1: an unsigned integer - * @cmp: The comparison operator to use. - * One of `==`, `!=`, `<`, `>`, `<=`, `>=`. - * @n2: another unsigned integer - * - * Debugging macro to compare two unsigned integers. - * - * The effect of `g_assert_cmpuint (n1, op, n2)` is - * the same as `g_assert_true (n1 op n2)`. The advantage - * of this macro is that it can produce a message that includes the - * actual values of @n1 and @n2. - * - * Since: 2.16 - */ - - -/** - * g_assert_cmpvariant: - * @v1: pointer to a #GVariant - * @v2: pointer to another #GVariant - * - * Debugging macro to compare two #GVariants. If the comparison fails, - * an error message is logged and the application is either terminated - * or the testcase marked as failed. The variants are compared using - * g_variant_equal(). - * - * The effect of `g_assert_cmpvariant (v1, v2)` is the same as - * `g_assert_true (g_variant_equal (v1, v2))`. The advantage of this macro is - * that it can produce a message that includes the actual values of @v1 and @v2. - * - * Since: 2.60 - */ - - -/** - * g_assert_error: - * @err: a #GError, possibly %NULL - * @dom: the expected error domain (a #GQuark) - * @c: the expected error code - * - * Debugging macro to check that a method has returned - * the correct #GError. - * - * The effect of `g_assert_error (err, dom, c)` is - * the same as `g_assert_true (err != NULL && err->domain - * == dom && err->code == c)`. The advantage of this - * macro is that it can produce a message that includes the incorrect - * error message and code. - * - * This can only be used to test for a specific error. If you want to - * test that @err is set, but don't care what it's set to, just use - * `g_assert_nonnull (err)`. - * - * Since: 2.20 - */ - - -/** - * g_assert_false: - * @expr: the expression to check - * - * Debugging macro to check an expression is false. - * - * If the assertion fails (i.e. the expression is not false), - * an error message is logged and the application is either - * terminated or the testcase marked as failed. - * - * Note that unlike g_assert(), this macro is unaffected by whether - * `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, - * conversely, g_assert() should not be used in tests. - * - * See g_test_set_nonfatal_assertions(). - * - * Since: 2.38 - */ - - -/** - * g_assert_no_errno: - * @expr: the expression to check - * - * Debugging macro to check that an expression has a non-negative return value, - * as used by traditional POSIX functions (such as `rmdir()`) to indicate - * success. - * - * If the assertion fails (i.e. the @expr returns a negative value), an error - * message is logged and the testcase is marked as failed. The error message - * will contain the value of `errno` and its human-readable message from - * g_strerror(). - * - * This macro will clear the value of `errno` before executing @expr. - * - * Since: 2.66 - */ - - -/** - * g_assert_no_error: - * @err: a #GError, possibly %NULL - * - * Debugging macro to check that a #GError is not set. - * - * The effect of `g_assert_no_error (err)` is - * the same as `g_assert_true (err == NULL)`. The advantage - * of this macro is that it can produce a message that includes - * the error message and code. - * - * Since: 2.20 - */ - - -/** - * g_assert_nonnull: - * @expr: the expression to check - * - * Debugging macro to check an expression is not %NULL. - * - * If the assertion fails (i.e. the expression is %NULL), - * an error message is logged and the application is either - * terminated or the testcase marked as failed. - * - * Note that unlike g_assert(), this macro is unaffected by whether - * `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, - * conversely, g_assert() should not be used in tests. - * - * See g_test_set_nonfatal_assertions(). - * - * Since: 2.40 - */ - - -/** - * g_assert_not_reached: - * - * Debugging macro to terminate the application if it is ever - * reached. If it is reached, an error message is logged and the - * application is terminated. - * - * The macro can be turned off in final releases of code by defining - * `G_DISABLE_ASSERT` when compiling the application. Hence, it should not be - * used in unit tests, where assertions should always be effective. - */ - - -/** - * g_assert_null: - * @expr: the expression to check - * - * Debugging macro to check an expression is %NULL. - * - * If the assertion fails (i.e. the expression is not %NULL), - * an error message is logged and the application is either - * terminated or the testcase marked as failed. - * - * Note that unlike g_assert(), this macro is unaffected by whether - * `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, - * conversely, g_assert() should not be used in tests. - * - * See g_test_set_nonfatal_assertions(). - * - * Since: 2.38 - */ - - -/** - * g_assert_true: - * @expr: the expression to check - * - * Debugging macro to check that an expression is true. - * - * If the assertion fails (i.e. the expression is not true), - * an error message is logged and the application is either - * terminated or the testcase marked as failed. - * - * Note that unlike g_assert(), this macro is unaffected by whether - * `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, - * conversely, g_assert() should not be used in tests. - * - * See g_test_set_nonfatal_assertions(). - * - * Since: 2.38 - */ - - -/** - * g_assertion_message_expr: (skip) - * @domain: (nullable): log domain - * @file: file containing the assertion - * @line: line number of the assertion - * @func: function containing the assertion - * @expr: (nullable): expression which failed - * - * Internal function used to print messages from the public g_assert() and - * g_assert_not_reached() macros. - */ - - -/** - * g_async_queue_length: - * @queue: a #GAsyncQueue. - * - * Returns the length of the queue. - * - * Actually this function returns the number of data items in - * the queue minus the number of waiting threads, so a negative - * value means waiting threads, and a positive value means available - * entries in the @queue. A return value of 0 could mean n entries - * in the queue and n threads waiting. This can happen due to locking - * of the queue or due to scheduling. - * - * Returns: the length of the @queue - */ - - -/** - * g_async_queue_length_unlocked: - * @queue: a #GAsyncQueue - * - * Returns the length of the queue. - * - * Actually this function returns the number of data items in - * the queue minus the number of waiting threads, so a negative - * value means waiting threads, and a positive value means available - * entries in the @queue. A return value of 0 could mean n entries - * in the queue and n threads waiting. This can happen due to locking - * of the queue or due to scheduling. - * - * This function must be called while holding the @queue's lock. - * - * Returns: the length of the @queue. - */ - - -/** - * g_async_queue_lock: - * @queue: a #GAsyncQueue - * - * Acquires the @queue's lock. If another thread is already - * holding the lock, this call will block until the lock - * becomes available. - * - * Call g_async_queue_unlock() to drop the lock again. - * - * While holding the lock, you can only call the - * g_async_queue_*_unlocked() functions on @queue. Otherwise, - * deadlock may occur. - */ - - -/** - * g_async_queue_new: - * - * Creates a new asynchronous queue. - * - * Returns: a new #GAsyncQueue. Free with g_async_queue_unref() - */ - - -/** - * g_async_queue_new_full: - * @item_free_func: (nullable): function to free queue elements - * - * Creates a new asynchronous queue and sets up a destroy notify - * function that is used to free any remaining queue items when - * the queue is destroyed after the final unref. - * - * Returns: a new #GAsyncQueue. Free with g_async_queue_unref() - * Since: 2.16 - */ - - -/** - * g_async_queue_pop: - * @queue: a #GAsyncQueue - * - * Pops data from the @queue. If @queue is empty, this function - * blocks until data becomes available. - * - * Returns: data from the queue - */ - - -/** - * g_async_queue_pop_unlocked: - * @queue: a #GAsyncQueue - * - * Pops data from the @queue. If @queue is empty, this function - * blocks until data becomes available. - * - * This function must be called while holding the @queue's lock. - * - * Returns: data from the queue. - */ - - -/** - * g_async_queue_push: - * @queue: a #GAsyncQueue - * @data: @data to push into the @queue - * - * Pushes the @data into the @queue. @data must not be %NULL. - */ - - -/** - * g_async_queue_push_front: - * @queue: a #GAsyncQueue - * @item: data to push into the @queue - * - * Pushes the @item into the @queue. @item must not be %NULL. - * In contrast to g_async_queue_push(), this function - * pushes the new item ahead of the items already in the queue, - * so that it will be the next one to be popped off the queue. - * - * Since: 2.46 - */ - - -/** - * g_async_queue_push_front_unlocked: - * @queue: a #GAsyncQueue - * @item: data to push into the @queue - * - * Pushes the @item into the @queue. @item must not be %NULL. - * In contrast to g_async_queue_push_unlocked(), this function - * pushes the new item ahead of the items already in the queue, - * so that it will be the next one to be popped off the queue. - * - * This function must be called while holding the @queue's lock. - * - * Since: 2.46 - */ - - -/** - * g_async_queue_push_sorted: - * @queue: a #GAsyncQueue - * @data: the @data to push into the @queue - * @func: the #GCompareDataFunc is used to sort @queue - * @user_data: user data passed to @func. - * - * Inserts @data into @queue using @func to determine the new - * position. - * - * This function requires that the @queue is sorted before pushing on - * new elements, see g_async_queue_sort(). - * - * This function will lock @queue before it sorts the queue and unlock - * it when it is finished. - * - * For an example of @func see g_async_queue_sort(). - * - * Since: 2.10 - */ - - -/** - * g_async_queue_push_sorted_unlocked: - * @queue: a #GAsyncQueue - * @data: the @data to push into the @queue - * @func: the #GCompareDataFunc is used to sort @queue - * @user_data: user data passed to @func. - * - * Inserts @data into @queue using @func to determine the new - * position. - * - * The sort function @func is passed two elements of the @queue. - * It should return 0 if they are equal, a negative value if the - * first element should be higher in the @queue or a positive value - * if the first element should be lower in the @queue than the second - * element. - * - * This function requires that the @queue is sorted before pushing on - * new elements, see g_async_queue_sort(). - * - * This function must be called while holding the @queue's lock. - * - * For an example of @func see g_async_queue_sort(). - * - * Since: 2.10 - */ - - -/** - * g_async_queue_push_unlocked: - * @queue: a #GAsyncQueue - * @data: @data to push into the @queue - * - * Pushes the @data into the @queue. @data must not be %NULL. - * - * This function must be called while holding the @queue's lock. - */ - - -/** - * g_async_queue_ref: - * @queue: a #GAsyncQueue - * - * Increases the reference count of the asynchronous @queue by 1. - * You do not need to hold the lock to call this function. - * - * Returns: the @queue that was passed in (since 2.6) - */ - - -/** - * g_async_queue_ref_unlocked: - * @queue: a #GAsyncQueue - * - * Increases the reference count of the asynchronous @queue by 1. - * - * Deprecated: 2.8: Reference counting is done atomically. - * so g_async_queue_ref() can be used regardless of the @queue's - * lock. - */ - - -/** - * g_async_queue_remove: - * @queue: a #GAsyncQueue - * @item: the data to remove from the @queue - * - * Remove an item from the queue. - * - * Returns: %TRUE if the item was removed - * Since: 2.46 - */ - - -/** - * g_async_queue_remove_unlocked: - * @queue: a #GAsyncQueue - * @item: the data to remove from the @queue - * - * Remove an item from the queue. - * - * This function must be called while holding the @queue's lock. - * - * Returns: %TRUE if the item was removed - * Since: 2.46 - */ - - -/** - * g_async_queue_sort: - * @queue: a #GAsyncQueue - * @func: the #GCompareDataFunc is used to sort @queue - * @user_data: user data passed to @func - * - * Sorts @queue using @func. - * - * The sort function @func is passed two elements of the @queue. - * It should return 0 if they are equal, a negative value if the - * first element should be higher in the @queue or a positive value - * if the first element should be lower in the @queue than the second - * element. - * - * This function will lock @queue before it sorts the queue and unlock - * it when it is finished. - * - * If you were sorting a list of priority numbers to make sure the - * lowest priority would be at the top of the queue, you could use: - * |[ - * gint32 id1; - * gint32 id2; - * - * id1 = GPOINTER_TO_INT (element1); - * id2 = GPOINTER_TO_INT (element2); - * - * return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1); - * ]| - * - * Since: 2.10 - */ - - -/** - * g_async_queue_sort_unlocked: - * @queue: a #GAsyncQueue - * @func: the #GCompareDataFunc is used to sort @queue - * @user_data: user data passed to @func - * - * Sorts @queue using @func. - * - * The sort function @func is passed two elements of the @queue. - * It should return 0 if they are equal, a negative value if the - * first element should be higher in the @queue or a positive value - * if the first element should be lower in the @queue than the second - * element. - * - * This function must be called while holding the @queue's lock. - * - * Since: 2.10 - */ - - -/** - * g_async_queue_timed_pop: - * @queue: a #GAsyncQueue - * @end_time: a #GTimeVal, determining the final time - * - * Pops data from the @queue. If the queue is empty, blocks until - * @end_time or until data becomes available. - * - * If no data is received before @end_time, %NULL is returned. - * - * To easily calculate @end_time, a combination of g_get_real_time() - * and g_time_val_add() can be used. - * - * Returns: (nullable): data from the queue or %NULL, when no data is - * received before @end_time. - * Deprecated: use g_async_queue_timeout_pop(). - */ - - -/** - * g_async_queue_timed_pop_unlocked: - * @queue: a #GAsyncQueue - * @end_time: a #GTimeVal, determining the final time - * - * Pops data from the @queue. If the queue is empty, blocks until - * @end_time or until data becomes available. - * - * If no data is received before @end_time, %NULL is returned. - * - * To easily calculate @end_time, a combination of g_get_real_time() - * and g_time_val_add() can be used. - * - * This function must be called while holding the @queue's lock. - * - * Returns: (nullable): data from the queue or %NULL, when no data is - * received before @end_time. - * Deprecated: use g_async_queue_timeout_pop_unlocked(). - */ - - -/** - * g_async_queue_timeout_pop: - * @queue: a #GAsyncQueue - * @timeout: the number of microseconds to wait - * - * Pops data from the @queue. If the queue is empty, blocks for - * @timeout microseconds, or until data becomes available. - * - * If no data is received before the timeout, %NULL is returned. - * - * Returns: (nullable): data from the queue or %NULL, when no data is - * received before the timeout. - */ - - -/** - * g_async_queue_timeout_pop_unlocked: - * @queue: a #GAsyncQueue - * @timeout: the number of microseconds to wait - * - * Pops data from the @queue. If the queue is empty, blocks for - * @timeout microseconds, or until data becomes available. - * - * If no data is received before the timeout, %NULL is returned. - * - * This function must be called while holding the @queue's lock. - * - * Returns: (nullable): data from the queue or %NULL, when no data is - * received before the timeout. - */ - - -/** - * g_async_queue_try_pop: - * @queue: a #GAsyncQueue - * - * Tries to pop data from the @queue. If no data is available, - * %NULL is returned. - * - * Returns: (nullable): data from the queue or %NULL, when no data is - * available immediately. - */ - - -/** - * g_async_queue_try_pop_unlocked: - * @queue: a #GAsyncQueue - * - * Tries to pop data from the @queue. If no data is available, - * %NULL is returned. - * - * This function must be called while holding the @queue's lock. - * - * Returns: (nullable): data from the queue or %NULL, when no data is - * available immediately. - */ - - -/** - * g_async_queue_unlock: - * @queue: a #GAsyncQueue - * - * Releases the queue's lock. - * - * Calling this function when you have not acquired - * the with g_async_queue_lock() leads to undefined - * behaviour. - */ - - -/** - * g_async_queue_unref: - * @queue: a #GAsyncQueue. - * - * Decreases the reference count of the asynchronous @queue by 1. - * - * If the reference count went to 0, the @queue will be destroyed - * and the memory allocated will be freed. So you are not allowed - * to use the @queue afterwards, as it might have disappeared. - * You do not need to hold the lock to call this function. - */ - - -/** - * g_async_queue_unref_and_unlock: - * @queue: a #GAsyncQueue - * - * Decreases the reference count of the asynchronous @queue by 1 - * and releases the lock. This function must be called while holding - * the @queue's lock. If the reference count went to 0, the @queue - * will be destroyed and the memory allocated will be freed. - * - * Deprecated: 2.8: Reference counting is done atomically. - * so g_async_queue_unref() can be used regardless of the @queue's - * lock. - */ - - -/** - * g_atexit: - * @func: (scope async): the function to call on normal program termination. - * - * Specifies a function to be called at normal program termination. - * - * Since GLib 2.8.2, on Windows g_atexit() actually is a preprocessor - * macro that maps to a call to the atexit() function in the C - * library. This means that in case the code that calls g_atexit(), - * i.e. atexit(), is in a DLL, the function will be called when the - * DLL is detached from the program. This typically makes more sense - * than that the function is called when the GLib DLL is detached, - * which happened earlier when g_atexit() was a function in the GLib - * DLL. - * - * The behaviour of atexit() in the context of dynamically loaded - * modules is not formally specified and varies wildly. - * - * On POSIX systems, calling g_atexit() (or atexit()) in a dynamically - * loaded module which is unloaded before the program terminates might - * well cause a crash at program exit. - * - * Some POSIX systems implement atexit() like Windows, and have each - * dynamically loaded module maintain an own atexit chain that is - * called when the module is unloaded. - * - * On other POSIX systems, before a dynamically loaded module is - * unloaded, the registered atexit functions (if any) residing in that - * module are called, regardless where the code that registered them - * resided. This is presumably the most robust approach. - * - * As can be seen from the above, for portability it's best to avoid - * calling g_atexit() (or atexit()) except in the main executable of a - * program. - * - * Deprecated: 2.32: It is best to avoid g_atexit(). - */ - - -/** - * g_atomic_int_add: - * @atomic: a pointer to a #gint or #guint - * @val: the value to add - * - * Atomically adds @val to the value of @atomic. - * - * Think of this operation as an atomic version of - * `{ tmp = *atomic; *atomic += val; return tmp; }`. - * - * This call acts as a full compiler and hardware memory barrier. - * - * Before version 2.30, this function did not return a value - * (but g_atomic_int_exchange_and_add() did, and had the same meaning). - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: the value of @atomic before the add, signed - * Since: 2.4 - */ - - -/** - * g_atomic_int_and: - * @atomic: a pointer to a #gint or #guint - * @val: the value to 'and' - * - * Performs an atomic bitwise 'and' of the value of @atomic and @val, - * storing the result back in @atomic. - * - * This call acts as a full compiler and hardware memory barrier. - * - * Think of this operation as an atomic version of - * `{ tmp = *atomic; *atomic &= val; return tmp; }`. - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: the value of @atomic before the operation, unsigned - * Since: 2.30 - */ - - -/** - * g_atomic_int_compare_and_exchange: - * @atomic: a pointer to a #gint or #guint - * @oldval: the value to compare with - * @newval: the value to conditionally replace with - * - * Compares @atomic to @oldval and, if equal, sets it to @newval. - * If @atomic was not equal to @oldval then no change occurs. - * - * This compare and exchange is done atomically. - * - * Think of this operation as an atomic version of - * `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. - * - * This call acts as a full compiler and hardware memory barrier. - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: %TRUE if the exchange took place - * Since: 2.4 - */ - - -/** - * g_atomic_int_dec_and_test: - * @atomic: a pointer to a #gint or #guint - * - * Decrements the value of @atomic by 1. - * - * Think of this operation as an atomic version of - * `{ *atomic -= 1; return (*atomic == 0); }`. - * - * This call acts as a full compiler and hardware memory barrier. - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: %TRUE if the resultant value is zero - * Since: 2.4 - */ - - -/** - * g_atomic_int_exchange_and_add: - * @atomic: a pointer to a #gint - * @val: the value to add - * - * This function existed before g_atomic_int_add() returned the prior - * value of the integer (which it now does). It is retained only for - * compatibility reasons. Don't use this function in new code. - * - * Returns: the value of @atomic before the add, signed - * Since: 2.4 - * Deprecated: 2.30: Use g_atomic_int_add() instead. - */ - - -/** - * g_atomic_int_get: - * @atomic: a pointer to a #gint or #guint - * - * Gets the current value of @atomic. - * - * This call acts as a full compiler and hardware - * memory barrier (before the get). - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: the value of the integer - * Since: 2.4 - */ - - -/** - * g_atomic_int_inc: - * @atomic: a pointer to a #gint or #guint - * - * Increments the value of @atomic by 1. - * - * Think of this operation as an atomic version of `{ *atomic += 1; }`. - * - * This call acts as a full compiler and hardware memory barrier. - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Since: 2.4 - */ - - -/** - * g_atomic_int_or: - * @atomic: a pointer to a #gint or #guint - * @val: the value to 'or' - * - * Performs an atomic bitwise 'or' of the value of @atomic and @val, - * storing the result back in @atomic. - * - * Think of this operation as an atomic version of - * `{ tmp = *atomic; *atomic |= val; return tmp; }`. - * - * This call acts as a full compiler and hardware memory barrier. - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: the value of @atomic before the operation, unsigned - * Since: 2.30 - */ - - -/** - * g_atomic_int_set: - * @atomic: a pointer to a #gint or #guint - * @newval: a new value to store - * - * Sets the value of @atomic to @newval. - * - * This call acts as a full compiler and hardware - * memory barrier (after the set). - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Since: 2.4 - */ - - -/** - * g_atomic_int_xor: - * @atomic: a pointer to a #gint or #guint - * @val: the value to 'xor' - * - * Performs an atomic bitwise 'xor' of the value of @atomic and @val, - * storing the result back in @atomic. - * - * Think of this operation as an atomic version of - * `{ tmp = *atomic; *atomic ^= val; return tmp; }`. - * - * This call acts as a full compiler and hardware memory barrier. - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: the value of @atomic before the operation, unsigned - * Since: 2.30 - */ - - -/** - * g_atomic_pointer_add: - * @atomic: (not nullable): a pointer to a #gpointer-sized value - * @val: the value to add - * - * Atomically adds @val to the value of @atomic. - * - * Think of this operation as an atomic version of - * `{ tmp = *atomic; *atomic += val; return tmp; }`. - * - * This call acts as a full compiler and hardware memory barrier. - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: the value of @atomic before the add, signed - * Since: 2.30 - */ - - -/** - * g_atomic_pointer_and: - * @atomic: (not nullable): a pointer to a #gpointer-sized value - * @val: the value to 'and' - * - * Performs an atomic bitwise 'and' of the value of @atomic and @val, - * storing the result back in @atomic. - * - * Think of this operation as an atomic version of - * `{ tmp = *atomic; *atomic &= val; return tmp; }`. - * - * This call acts as a full compiler and hardware memory barrier. - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: the value of @atomic before the operation, unsigned - * Since: 2.30 - */ - - -/** - * g_atomic_pointer_compare_and_exchange: - * @atomic: (not nullable): a pointer to a #gpointer-sized value - * @oldval: the value to compare with - * @newval: the value to conditionally replace with - * - * Compares @atomic to @oldval and, if equal, sets it to @newval. - * If @atomic was not equal to @oldval then no change occurs. - * - * This compare and exchange is done atomically. - * - * Think of this operation as an atomic version of - * `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. - * - * This call acts as a full compiler and hardware memory barrier. - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: %TRUE if the exchange took place - * Since: 2.4 - */ - - -/** - * g_atomic_pointer_get: - * @atomic: (not nullable): a pointer to a #gpointer-sized value - * - * Gets the current value of @atomic. - * - * This call acts as a full compiler and hardware - * memory barrier (before the get). - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: the value of the pointer - * Since: 2.4 - */ - - -/** - * g_atomic_pointer_or: - * @atomic: (not nullable): a pointer to a #gpointer-sized value - * @val: the value to 'or' - * - * Performs an atomic bitwise 'or' of the value of @atomic and @val, - * storing the result back in @atomic. - * - * Think of this operation as an atomic version of - * `{ tmp = *atomic; *atomic |= val; return tmp; }`. - * - * This call acts as a full compiler and hardware memory barrier. - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: the value of @atomic before the operation, unsigned - * Since: 2.30 - */ - - -/** - * g_atomic_pointer_set: - * @atomic: (not nullable): a pointer to a #gpointer-sized value - * @newval: a new value to store - * - * Sets the value of @atomic to @newval. - * - * This call acts as a full compiler and hardware - * memory barrier (after the set). - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Since: 2.4 - */ - - -/** - * g_atomic_pointer_xor: - * @atomic: (not nullable): a pointer to a #gpointer-sized value - * @val: the value to 'xor' - * - * Performs an atomic bitwise 'xor' of the value of @atomic and @val, - * storing the result back in @atomic. - * - * Think of this operation as an atomic version of - * `{ tmp = *atomic; *atomic ^= val; return tmp; }`. - * - * This call acts as a full compiler and hardware memory barrier. - * - * While @atomic has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: the value of @atomic before the operation, unsigned - * Since: 2.30 - */ - - -/** - * g_atomic_rc_box_acquire: - * @mem_block: (not nullable): a pointer to reference counted data - * - * Atomically acquires a reference on the data pointed by @mem_block. - * - * Returns: (transfer full) (not nullable): a pointer to the data, - * with its reference count increased - * Since: 2.58 - */ - - -/** - * g_atomic_rc_box_alloc: - * @block_size: the size of the allocation, must be greater than 0 - * - * Allocates @block_size bytes of memory, and adds atomic - * reference counting semantics to it. - * - * The data will be freed when its reference count drops to - * zero. - * - * The allocated data is guaranteed to be suitably aligned for any - * built-in type. - * - * Returns: (transfer full) (not nullable): a pointer to the allocated memory - * Since: 2.58 - */ - - -/** - * g_atomic_rc_box_alloc0: - * @block_size: the size of the allocation, must be greater than 0 - * - * Allocates @block_size bytes of memory, and adds atomic - * reference counting semantics to it. - * - * The contents of the returned data is set to zero. - * - * The data will be freed when its reference count drops to - * zero. - * - * The allocated data is guaranteed to be suitably aligned for any - * built-in type. - * - * Returns: (transfer full) (not nullable): a pointer to the allocated memory - * Since: 2.58 - */ - - -/** - * g_atomic_rc_box_dup: - * @block_size: the number of bytes to copy, must be greater than 0 - * @mem_block: (not nullable): the memory to copy - * - * Allocates a new block of data with atomic reference counting - * semantics, and copies @block_size bytes of @mem_block - * into it. - * - * Returns: (transfer full) (not nullable): a pointer to the allocated - * memory - * Since: 2.58 - */ - - -/** - * g_atomic_rc_box_get_size: - * @mem_block: (not nullable): a pointer to reference counted data - * - * Retrieves the size of the reference counted data pointed by @mem_block. - * - * Returns: the size of the data, in bytes - * Since: 2.58 - */ - - -/** - * g_atomic_rc_box_new: - * @type: the type to allocate, typically a structure name - * - * A convenience macro to allocate atomically reference counted - * data with the size of the given @type. - * - * This macro calls g_atomic_rc_box_alloc() with `sizeof (@type)` and - * casts the returned pointer to a pointer of the given @type, - * avoiding a type cast in the source code. - * - * Returns: (transfer full) (not nullable): a pointer to the allocated - * memory, cast to a pointer for the given @type - * Since: 2.58 - */ - - -/** - * g_atomic_rc_box_new0: - * @type: the type to allocate, typically a structure name - * - * A convenience macro to allocate atomically reference counted - * data with the size of the given @type, and set its contents - * to zero. - * - * This macro calls g_atomic_rc_box_alloc0() with `sizeof (@type)` and - * casts the returned pointer to a pointer of the given @type, - * avoiding a type cast in the source code. - * - * Returns: (transfer full) (not nullable): a pointer to the allocated - * memory, cast to a pointer for the given @type - * Since: 2.58 - */ - - -/** - * g_atomic_rc_box_release: - * @mem_block: (transfer full) (not nullable): a pointer to reference counted data - * - * Atomically releases a reference on the data pointed by @mem_block. - * - * If the reference was the last one, it will free the - * resources allocated for @mem_block. - * - * Since: 2.58 - */ - - -/** - * g_atomic_rc_box_release_full: - * @mem_block: (transfer full) (not nullable): a pointer to reference counted data - * @clear_func: (not nullable): a function to call when clearing the data - * - * Atomically releases a reference on the data pointed by @mem_block. - * - * If the reference was the last one, it will call @clear_func - * to clear the contents of @mem_block, and then will free the - * resources allocated for @mem_block. - * - * Since: 2.58 - */ - - -/** - * g_atomic_ref_count_compare: - * @arc: the address of an atomic reference count variable - * @val: the value to compare - * - * Atomically compares the current value of @arc with @val. - * - * Returns: %TRUE if the reference count is the same - * as the given value - * Since: 2.58 - */ - - -/** - * g_atomic_ref_count_dec: - * @arc: the address of an atomic reference count variable - * - * Atomically decreases the reference count. - * - * If %TRUE is returned, the reference count reached 0. After this point, @arc - * is an undefined state and must be reinitialized with - * g_atomic_ref_count_init() to be used again. - * - * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise - * Since: 2.58 - */ - - -/** - * g_atomic_ref_count_inc: - * @arc: the address of an atomic reference count variable - * - * Atomically increases the reference count. - * - * Since: 2.58 - */ - - -/** - * g_atomic_ref_count_init: - * @arc: the address of an atomic reference count variable - * - * Initializes a reference count variable to 1. - * - * Since: 2.58 - */ - - -/** - * g_auto: - * @TypeName: a supported variable type - * - * Helper to declare a variable with automatic cleanup. - * - * The variable is cleaned up in a way appropriate to its type when the - * variable goes out of scope. The type must support this. - * The way to clean up the type must have been defined using one of the macros - * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC() or G_DEFINE_AUTO_CLEANUP_FREE_FUNC(). - * - * This feature is only supported on GCC and clang. This macro is not - * defined on other compilers and should not be used in programs that - * are intended to be portable to those compilers. - * - * This is meant to be used with stack-allocated structures and - * non-pointer types. For the (more commonly used) pointer version, see - * g_autoptr(). - * - * This macro can be used to avoid having to do explicit cleanups of - * local variables when exiting functions. It often vastly simplifies - * handling of error conditions, removing the need for various tricks - * such as `goto out` or repeating of cleanup code. It is also helpful - * for non-error cases. - * - * Consider the following example: - * - * |[ - * GVariant * - * my_func(void) - * { - * g_auto(GQueue) queue = G_QUEUE_INIT; - * g_auto(GVariantBuilder) builder; - * g_auto(GStrv) strv; - * - * g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT); - * strv = g_strsplit("a:b:c", ":", -1); - * - * ... - * - * if (error_condition) - * return NULL; - * - * ... - * - * return g_variant_builder_end (&builder); - * } - * ]| - * - * You must initialize the variable in some way — either by use of an - * initialiser or by ensuring that an `_init` function will be called on - * it unconditionally before it goes out of scope. - * - * Since: 2.44 - */ - - -/** - * g_autofree: - * - * Macro to add an attribute to pointer variable to ensure automatic - * cleanup using g_free(). - * - * This macro differs from g_autoptr() in that it is an attribute supplied - * before the type name, rather than wrapping the type definition. Instead - * of using a type-specific lookup, this macro always calls g_free() directly. - * - * This means it's useful for any type that is returned from - * g_malloc(). - * - * Otherwise, this macro has similar constraints as g_autoptr(): only - * supported on GCC and clang, the variable must be initialized, etc. - * - * |[ - * gboolean - * operate_on_malloc_buf (void) - * { - * g_autofree guint8* membuf = NULL; - * - * membuf = g_malloc (8192); - * - * // Some computation on membuf - * - * // membuf will be automatically freed here - * return TRUE; - * } - * ]| - * - * Since: 2.44 - */ - - -/** - * g_autolist: - * @TypeName: a supported variable type - * - * Helper to declare a list variable with automatic deep cleanup. - * - * The list is deeply freed, in a way appropriate to the specified type, when the - * variable goes out of scope. The type must support this. - * - * This feature is only supported on GCC and clang. This macro is not - * defined on other compilers and should not be used in programs that - * are intended to be portable to those compilers. - * - * This is meant to be used to declare lists of a type with a cleanup - * function. The type of the variable is a `GList *`. You - * must not add your own `*`. - * - * This macro can be used to avoid having to do explicit cleanups of - * local variables when exiting functions. It often vastly simplifies - * handling of error conditions, removing the need for various tricks - * such as `goto out` or repeating of cleanup code. It is also helpful - * for non-error cases. - * - * See also g_autoslist(), g_autoptr() and g_steal_pointer(). - * - * Since: 2.56 - */ - - -/** - * g_autoptr: - * @TypeName: a supported variable type - * - * Helper to declare a pointer variable with automatic cleanup. - * - * The variable is cleaned up in a way appropriate to its type when the - * variable goes out of scope. The type must support this. - * The way to clean up the type must have been defined using the macro - * G_DEFINE_AUTOPTR_CLEANUP_FUNC(). - * - * This feature is only supported on GCC and clang. This macro is not - * defined on other compilers and should not be used in programs that - * are intended to be portable to those compilers. - * - * This is meant to be used to declare pointers to types with cleanup - * functions. The type of the variable is a pointer to @TypeName. You - * must not add your own `*`. - * - * This macro can be used to avoid having to do explicit cleanups of - * local variables when exiting functions. It often vastly simplifies - * handling of error conditions, removing the need for various tricks - * such as `goto out` or repeating of cleanup code. It is also helpful - * for non-error cases. - * - * Consider the following example: - * - * |[ - * gboolean - * check_exists(GVariant *dict) - * { - * g_autoptr(GVariant) dirname, basename = NULL; - * g_autofree gchar *path = NULL; - * - * dirname = g_variant_lookup_value (dict, "dirname", G_VARIANT_TYPE_STRING); - * - * if (dirname == NULL) - * return FALSE; - * - * basename = g_variant_lookup_value (dict, "basename", G_VARIANT_TYPE_STRING); - * - * if (basename == NULL) - * return FALSE; - * - * path = g_build_filename (g_variant_get_string (dirname, NULL), - * g_variant_get_string (basename, NULL), - * NULL); - * - * return g_access (path, R_OK) == 0; - * } - * ]| - * - * You must initialise the variable in some way — either by use of an - * initialiser or by ensuring that it is assigned to unconditionally - * before it goes out of scope. - * - * See also g_auto(), g_autofree() and g_steal_pointer(). - * - * Since: 2.44 - */ - - -/** - * g_autoqueue: - * @TypeName: a supported variable type - * - * Helper to declare a double-ended queue variable with automatic deep cleanup. - * - * The queue is deeply freed, in a way appropriate to the specified type, when the - * variable goes out of scope. The type must support this. - * - * This feature is only supported on GCC and clang. This macro is not - * defined on other compilers and should not be used in programs that - * are intended to be portable to those compilers. - * - * This is meant to be used to declare queues of a type with a cleanup - * function. The type of the variable is a `GQueue *`. You - * must not add your own `*`. - * - * This macro can be used to avoid having to do explicit cleanups of - * local variables when exiting functions. It often vastly simplifies - * handling of error conditions, removing the need for various tricks - * such as `goto out` or repeating of cleanup code. It is also helpful - * for non-error cases. - * - * See also g_autolist(), g_autoptr() and g_steal_pointer(). - * - * Since: 2.62 - */ - - -/** - * g_autoslist: - * @TypeName: a supported variable type - * - * Helper to declare a singly linked list variable with automatic deep cleanup. - * - * The list is deeply freed, in a way appropriate to the specified type, when the - * variable goes out of scope. The type must support this. - * - * This feature is only supported on GCC and clang. This macro is not - * defined on other compilers and should not be used in programs that - * are intended to be portable to those compilers. - * - * This is meant to be used to declare lists of a type with a cleanup - * function. The type of the variable is a `GSList *`. You - * must not add your own `*`. - * - * This macro can be used to avoid having to do explicit cleanups of - * local variables when exiting functions. It often vastly simplifies - * handling of error conditions, removing the need for various tricks - * such as `goto out` or repeating of cleanup code. It is also helpful - * for non-error cases. - * - * See also g_autolist(), g_autoptr() and g_steal_pointer(). - * - * Since: 2.56 - */ - - -/** - * g_base64_decode: - * @text: (not nullable): zero-terminated string with base64 text to decode - * @out_len: (out): The length of the decoded data is written here - * - * Decode a sequence of Base-64 encoded text into binary data. Note - * that the returned binary data is not necessarily zero-terminated, - * so it should not be used as a character string. - * - * Returns: (transfer full) (array length=out_len) (element-type guint8): - * newly allocated buffer containing the binary data - * that @text represents. The returned buffer must - * be freed with g_free(). - * Since: 2.12 - */ - - -/** - * g_base64_decode_inplace: - * @text: (inout) (array length=out_len) (element-type guint8): zero-terminated - * string with base64 text to decode - * @out_len: (inout): The length of the decoded data is written here - * - * Decode a sequence of Base-64 encoded text into binary data - * by overwriting the input data. - * - * Returns: (transfer none): The binary data that @text responds. This pointer - * is the same as the input @text. - * Since: 2.20 - */ - - -/** - * g_base64_decode_step: (skip) - * @in: (array length=len) (element-type guint8): binary input data - * @len: max length of @in data to decode - * @out: (out caller-allocates) (array) (element-type guint8): output buffer - * @state: (inout): Saved state between steps, initialize to 0 - * @save: (inout): Saved state between steps, initialize to 0 - * - * Incrementally decode a sequence of binary data from its Base-64 stringified - * representation. By calling this function multiple times you can convert - * data in chunks to avoid having to have the full encoded data in memory. - * - * The output buffer must be large enough to fit all the data that will - * be written to it. Since base64 encodes 3 bytes in 4 chars you need - * at least: (@len / 4) * 3 + 3 bytes (+ 3 may be needed in case of non-zero - * state). - * - * Returns: The number of bytes of output that was written - * Since: 2.12 - */ - - -/** - * g_base64_encode: - * @data: (array length=len) (element-type guint8) (nullable): the binary data to encode - * @len: the length of @data - * - * Encode a sequence of binary data into its Base-64 stringified - * representation. - * - * Returns: (transfer full): a newly allocated, zero-terminated Base-64 - * encoded string representing @data. The returned string must - * be freed with g_free(). - * Since: 2.12 - */ - - -/** - * g_base64_encode_close: - * @break_lines: whether to break long lines - * @out: (out) (array) (element-type guint8): pointer to destination buffer - * @state: (inout): Saved state from g_base64_encode_step() - * @save: (inout): Saved state from g_base64_encode_step() - * - * Flush the status from a sequence of calls to g_base64_encode_step(). - * - * The output buffer must be large enough to fit all the data that will - * be written to it. It will need up to 4 bytes, or up to 5 bytes if - * line-breaking is enabled. - * - * The @out array will not be automatically nul-terminated. - * - * Returns: The number of bytes of output that was written - * Since: 2.12 - */ - - -/** - * g_base64_encode_step: - * @in: (array length=len) (element-type guint8): the binary data to encode - * @len: the length of @in - * @break_lines: whether to break long lines - * @out: (out) (array) (element-type guint8): pointer to destination buffer - * @state: (inout): Saved state between steps, initialize to 0 - * @save: (inout): Saved state between steps, initialize to 0 - * - * Incrementally encode a sequence of binary data into its Base-64 stringified - * representation. By calling this function multiple times you can convert - * data in chunks to avoid having to have the full encoded data in memory. - * - * When all of the data has been converted you must call - * g_base64_encode_close() to flush the saved state. - * - * The output buffer must be large enough to fit all the data that will - * be written to it. Due to the way base64 encodes you will need - * at least: (@len / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of - * non-zero state). If you enable line-breaking you will need at least: - * ((@len / 3 + 1) * 4 + 4) / 76 + 1 bytes of extra space. - * - * @break_lines is typically used when putting base64-encoded data in emails. - * It breaks the lines at 76 columns instead of putting all of the text on - * the same line. This avoids problems with long lines in the email system. - * Note however that it breaks the lines with `LF` characters, not - * `CR LF` sequences, so the result cannot be passed directly to SMTP - * or certain other protocols. - * - * Returns: The number of bytes of output that was written - * Since: 2.12 - */ - - -/** - * g_basename: - * @file_name: (type filename): the name of the file - * - * Gets the name of the file without any leading directory - * components. It returns a pointer into the given file name - * string. - * - * Returns: (type filename): the name of the file without any leading - * directory components - * Deprecated: 2.2: Use g_path_get_basename() instead, but notice - * that g_path_get_basename() allocates new memory for the - * returned string, unlike this function which returns a pointer - * into the argument. - */ - - -/** - * g_bit_lock: - * @address: a pointer to an integer - * @lock_bit: a bit value between 0 and 31 - * - * Sets the indicated @lock_bit in @address. If the bit is already - * set, this call will block until g_bit_unlock() unsets the - * corresponding bit. - * - * Attempting to lock on two different bits within the same integer is - * not supported and will very probably cause deadlocks. - * - * The value of the bit that is set is (1u << @bit). If @bit is not - * between 0 and 31 then the result is undefined. - * - * This function accesses @address atomically. All other accesses to - * @address must be atomic in order for this function to work - * reliably. While @address has a `volatile` qualifier, this is a historical - * artifact and the argument passed to it should not be `volatile`. - * - * Since: 2.24 - */ - - -/** - * g_bit_nth_lsf: - * @mask: a #gulong containing flags - * @nth_bit: the index of the bit to start the search from - * - * Find the position of the first bit set in @mask, searching - * from (but not including) @nth_bit upwards. Bits are numbered - * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, - * usually). To start searching from the 0th bit, set @nth_bit to -1. - * - * Returns: the index of the first bit set which is higher than @nth_bit, or -1 - * if no higher bits are set - */ - - -/** - * g_bit_nth_msf: - * @mask: a #gulong containing flags - * @nth_bit: the index of the bit to start the search from - * - * Find the position of the first bit set in @mask, searching - * from (but not including) @nth_bit downwards. Bits are numbered - * from 0 (least significant) to sizeof(#gulong) * 8 - 1 (31 or 63, - * usually). To start searching from the last bit, set @nth_bit to - * -1 or GLIB_SIZEOF_LONG * 8. - * - * Returns: the index of the first bit set which is lower than @nth_bit, or -1 - * if no lower bits are set - */ - - -/** - * g_bit_storage: - * @number: a #guint - * - * Gets the number of bits used to hold @number, - * e.g. if @number is 4, 3 bits are needed. - * - * Returns: the number of bits used to hold @number - */ - - -/** - * g_bit_trylock: - * @address: a pointer to an integer - * @lock_bit: a bit value between 0 and 31 - * - * Sets the indicated @lock_bit in @address, returning %TRUE if - * successful. If the bit is already set, returns %FALSE immediately. - * - * Attempting to lock on two different bits within the same integer is - * not supported. - * - * The value of the bit that is set is (1u << @bit). If @bit is not - * between 0 and 31 then the result is undefined. - * - * This function accesses @address atomically. All other accesses to - * @address must be atomic in order for this function to work - * reliably. While @address has a `volatile` qualifier, this is a historical - * artifact and the argument passed to it should not be `volatile`. - * - * Returns: %TRUE if the lock was acquired - * Since: 2.24 - */ - - -/** - * g_bit_unlock: - * @address: a pointer to an integer - * @lock_bit: a bit value between 0 and 31 - * - * Clears the indicated @lock_bit in @address. If another thread is - * currently blocked in g_bit_lock() on this same bit then it will be - * woken up. - * - * This function accesses @address atomically. All other accesses to - * @address must be atomic in order for this function to work - * reliably. While @address has a `volatile` qualifier, this is a historical - * artifact and the argument passed to it should not be `volatile`. - * - * Since: 2.24 - */ - - -/** - * g_bookmark_file_add_application: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @name: (nullable): the name of the application registering the bookmark - * or %NULL - * @exec: (nullable): command line to be used to launch the bookmark or %NULL - * - * Adds the application with @name and @exec to the list of - * applications that have registered a bookmark for @uri into - * @bookmark. - * - * Every bookmark inside a #GBookmarkFile must have at least an - * application registered. Each application must provide a name, a - * command line useful for launching the bookmark, the number of times - * the bookmark has been registered by the application and the last - * time the application registered this bookmark. - * - * If @name is %NULL, the name of the application will be the - * same returned by g_get_application_name(); if @exec is %NULL, the - * command line will be a composition of the program name as - * returned by g_get_prgname() and the "\%u" modifier, which will be - * expanded to the bookmark's URI. - * - * This function will automatically take care of updating the - * registrations count and timestamping in case an application - * with the same @name had already registered a bookmark for - * @uri inside @bookmark. - * - * If no bookmark for @uri is found, one is created. - * - * Since: 2.12 - */ - - -/** - * g_bookmark_file_add_group: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @group: the group name to be added - * - * Adds @group to the list of groups to which the bookmark for @uri - * belongs to. - * - * If no bookmark for @uri is found then it is created. - * - * Since: 2.12 - */ - - -/** - * g_bookmark_file_free: - * @bookmark: a #GBookmarkFile - * - * Frees a #GBookmarkFile. - * - * Since: 2.12 - */ - - -/** - * g_bookmark_file_get_added: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @error: return location for a #GError, or %NULL - * - * Gets the time the bookmark for @uri was added to @bookmark - * - * In the event the URI cannot be found, -1 is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: a timestamp - * Since: 2.12 - * Deprecated: 2.66: Use g_bookmark_file_get_added_date_time() instead, as - * `time_t` is deprecated due to the year 2038 problem. - */ - - -/** - * g_bookmark_file_get_added_date_time: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @error: return location for a #GError, or %NULL - * - * Gets the time the bookmark for @uri was added to @bookmark - * - * In the event the URI cannot be found, %NULL is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: (transfer none): a #GDateTime - * Since: 2.66 - */ - - -/** - * g_bookmark_file_get_app_info: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @name: an application's name - * @exec: (out) (optional): return location for the command line of the application, or %NULL - * @count: (out) (optional): return location for the registration count, or %NULL - * @stamp: (out) (optional): return location for the last registration time, or %NULL - * @error: return location for a #GError, or %NULL - * - * Gets the registration information of @app_name for the bookmark for - * @uri. See g_bookmark_file_set_application_info() for more information about - * the returned data. - * - * The string returned in @app_exec must be freed. - * - * In the event the URI cannot be found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the - * event that no application with name @app_name has registered a bookmark - * for @uri, %FALSE is returned and error is set to - * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting - * the command line fails, an error of the #G_SHELL_ERROR domain is - * set and %FALSE is returned. - * - * Returns: %TRUE on success. - * Since: 2.12 - * Deprecated: 2.66: Use g_bookmark_file_get_application_info() instead, as - * `time_t` is deprecated due to the year 2038 problem. - */ - - -/** - * g_bookmark_file_get_application_info: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @name: an application's name - * @exec: (out) (optional): return location for the command line of the application, or %NULL - * @count: (out) (optional): return location for the registration count, or %NULL - * @stamp: (out) (optional) (transfer none): return location for the last registration time, or %NULL - * @error: return location for a #GError, or %NULL - * - * Gets the registration information of @app_name for the bookmark for - * @uri. See g_bookmark_file_set_application_info() for more information about - * the returned data. - * - * The string returned in @app_exec must be freed. - * - * In the event the URI cannot be found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the - * event that no application with name @app_name has registered a bookmark - * for @uri, %FALSE is returned and error is set to - * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting - * the command line fails, an error of the #G_SHELL_ERROR domain is - * set and %FALSE is returned. - * - * Returns: %TRUE on success. - * Since: 2.66 - */ - - -/** - * g_bookmark_file_get_applications: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @length: (out) (optional): return location of the length of the returned list, or %NULL - * @error: return location for a #GError, or %NULL - * - * Retrieves the names of the applications that have registered the - * bookmark for @uri. - * - * In the event the URI cannot be found, %NULL is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. - * Use g_strfreev() to free it. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_get_description: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @error: return location for a #GError, or %NULL - * - * Retrieves the description of the bookmark for @uri. - * - * In the event the URI cannot be found, %NULL is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: (transfer full): a newly allocated string or %NULL if the specified - * URI cannot be found. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_get_groups: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @length: (out) (optional): return location for the length of the returned string, or %NULL - * @error: return location for a #GError, or %NULL - * - * Retrieves the list of group names of the bookmark for @uri. - * - * In the event the URI cannot be found, %NULL is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * The returned array is %NULL terminated, so @length may optionally - * be %NULL. - * - * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of group names. - * Use g_strfreev() to free it. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_get_icon: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @href: (out) (optional): return location for the icon's location or %NULL - * @mime_type: (out) (optional): return location for the icon's MIME type or %NULL - * @error: return location for a #GError or %NULL - * - * Gets the icon of the bookmark for @uri. - * - * In the event the URI cannot be found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: %TRUE if the icon for the bookmark for the URI was found. - * You should free the returned strings. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_get_is_private: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @error: return location for a #GError, or %NULL - * - * Gets whether the private flag of the bookmark for @uri is set. - * - * In the event the URI cannot be found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the - * event that the private flag cannot be found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. - * - * Returns: %TRUE if the private flag is set, %FALSE otherwise. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_get_mime_type: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @error: return location for a #GError, or %NULL - * - * Retrieves the MIME type of the resource pointed by @uri. - * - * In the event the URI cannot be found, %NULL is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the - * event that the MIME type cannot be found, %NULL is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. - * - * Returns: (transfer full): a newly allocated string or %NULL if the specified - * URI cannot be found. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_get_modified: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @error: return location for a #GError, or %NULL - * - * Gets the time when the bookmark for @uri was last modified. - * - * In the event the URI cannot be found, -1 is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: a timestamp - * Since: 2.12 - * Deprecated: 2.66: Use g_bookmark_file_get_modified_date_time() instead, as - * `time_t` is deprecated due to the year 2038 problem. - */ - - -/** - * g_bookmark_file_get_modified_date_time: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @error: return location for a #GError, or %NULL - * - * Gets the time when the bookmark for @uri was last modified. - * - * In the event the URI cannot be found, %NULL is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: (transfer none): a #GDateTime - * Since: 2.66 - */ - - -/** - * g_bookmark_file_get_size: - * @bookmark: a #GBookmarkFile - * - * Gets the number of bookmarks inside @bookmark. - * - * Returns: the number of bookmarks - * Since: 2.12 - */ - - -/** - * g_bookmark_file_get_title: - * @bookmark: a #GBookmarkFile - * @uri: (nullable): a valid URI or %NULL - * @error: return location for a #GError, or %NULL - * - * Returns the title of the bookmark for @uri. - * - * If @uri is %NULL, the title of @bookmark is returned. - * - * In the event the URI cannot be found, %NULL is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: (transfer full): a newly allocated string or %NULL if the specified - * URI cannot be found. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_get_uris: - * @bookmark: a #GBookmarkFile - * @length: (out) (optional): return location for the number of returned URIs, or %NULL - * - * Returns all URIs of the bookmarks in the bookmark file @bookmark. - * The array of returned URIs will be %NULL-terminated, so @length may - * optionally be %NULL. - * - * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. - * Use g_strfreev() to free it. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_get_visited: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @error: return location for a #GError, or %NULL - * - * Gets the time the bookmark for @uri was last visited. - * - * In the event the URI cannot be found, -1 is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: a timestamp. - * Since: 2.12 - * Deprecated: 2.66: Use g_bookmark_file_get_visited_date_time() instead, as - * `time_t` is deprecated due to the year 2038 problem. - */ - - -/** - * g_bookmark_file_get_visited_date_time: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @error: return location for a #GError, or %NULL - * - * Gets the time the bookmark for @uri was last visited. - * - * In the event the URI cannot be found, %NULL is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: (transfer none): a #GDateTime - * Since: 2.66 - */ - - -/** - * g_bookmark_file_has_application: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @name: the name of the application - * @error: return location for a #GError or %NULL - * - * Checks whether the bookmark for @uri inside @bookmark has been - * registered by application @name. - * - * In the event the URI cannot be found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: %TRUE if the application @name was found - * Since: 2.12 - */ - - -/** - * g_bookmark_file_has_group: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @group: the group name to be searched - * @error: return location for a #GError, or %NULL - * - * Checks whether @group appears in the list of groups to which - * the bookmark for @uri belongs to. - * - * In the event the URI cannot be found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: %TRUE if @group was found. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_has_item: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * - * Looks whether the desktop bookmark has an item with its URI set to @uri. - * - * Returns: %TRUE if @uri is inside @bookmark, %FALSE otherwise - * Since: 2.12 - */ - - -/** - * g_bookmark_file_load_from_data: - * @bookmark: an empty #GBookmarkFile struct - * @data: (array length=length) (element-type guint8): desktop bookmarks - * loaded in memory - * @length: the length of @data in bytes - * @error: return location for a #GError, or %NULL - * - * Loads a bookmark file from memory into an empty #GBookmarkFile - * structure. If the object cannot be created then @error is set to a - * #GBookmarkFileError. - * - * Returns: %TRUE if a desktop bookmark could be loaded. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_load_from_data_dirs: - * @bookmark: a #GBookmarkFile - * @file: (type filename): a relative path to a filename to open and parse - * @full_path: (out) (optional) (type filename): return location for a string - * containing the full path of the file, or %NULL - * @error: return location for a #GError, or %NULL - * - * This function looks for a desktop bookmark file named @file in the - * paths returned from g_get_user_data_dir() and g_get_system_data_dirs(), - * loads the file into @bookmark and returns the file's full path in - * @full_path. If the file could not be loaded then @error is - * set to either a #GFileError or #GBookmarkFileError. - * - * Returns: %TRUE if a key file could be loaded, %FALSE otherwise - * Since: 2.12 - */ - - -/** - * g_bookmark_file_load_from_file: - * @bookmark: an empty #GBookmarkFile struct - * @filename: (type filename): the path of a filename to load, in the - * GLib file name encoding - * @error: return location for a #GError, or %NULL - * - * Loads a desktop bookmark file into an empty #GBookmarkFile structure. - * If the file could not be loaded then @error is set to either a #GFileError - * or #GBookmarkFileError. - * - * Returns: %TRUE if a desktop bookmark file could be loaded - * Since: 2.12 - */ - - -/** - * g_bookmark_file_move_item: - * @bookmark: a #GBookmarkFile - * @old_uri: a valid URI - * @new_uri: (nullable): a valid URI, or %NULL - * @error: return location for a #GError or %NULL - * - * Changes the URI of a bookmark item from @old_uri to @new_uri. Any - * existing bookmark for @new_uri will be overwritten. If @new_uri is - * %NULL, then the bookmark is removed. - * - * In the event the URI cannot be found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * - * Returns: %TRUE if the URI was successfully changed - * Since: 2.12 - */ - - -/** - * g_bookmark_file_new: (constructor) - * - * Creates a new empty #GBookmarkFile object. - * - * Use g_bookmark_file_load_from_file(), g_bookmark_file_load_from_data() - * or g_bookmark_file_load_from_data_dirs() to read an existing bookmark - * file. - * - * Returns: an empty #GBookmarkFile - * Since: 2.12 - */ - - -/** - * g_bookmark_file_remove_application: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @name: the name of the application - * @error: return location for a #GError or %NULL - * - * Removes application registered with @name from the list of applications - * that have registered a bookmark for @uri inside @bookmark. - * - * In the event the URI cannot be found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * In the event that no application with name @app_name has registered - * a bookmark for @uri, %FALSE is returned and error is set to - * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. - * - * Returns: %TRUE if the application was successfully removed. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_remove_group: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @group: the group name to be removed - * @error: return location for a #GError, or %NULL - * - * Removes @group from the list of groups to which the bookmark - * for @uri belongs to. - * - * In the event the URI cannot be found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. - * In the event no group was defined, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. - * - * Returns: %TRUE if @group was successfully removed. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_remove_item: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @error: return location for a #GError, or %NULL - * - * Removes the bookmark for @uri from the bookmark file @bookmark. - * - * Returns: %TRUE if the bookmark was removed successfully. - * Since: 2.12 - */ - - -/** - * g_bookmark_file_set_added: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @added: a timestamp or -1 to use the current time - * - * Sets the time the bookmark for @uri was added into @bookmark. - * - * If no bookmark for @uri is found then it is created. - * - * Since: 2.12 - * Deprecated: 2.66: Use g_bookmark_file_set_added_date_time() instead, as - * `time_t` is deprecated due to the year 2038 problem. - */ - - -/** - * g_bookmark_file_set_added_date_time: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @added: a #GDateTime - * - * Sets the time the bookmark for @uri was added into @bookmark. - * - * If no bookmark for @uri is found then it is created. - * - * Since: 2.66 - */ - - -/** - * g_bookmark_file_set_app_info: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @name: an application's name - * @exec: an application's command line - * @count: the number of registrations done for this application - * @stamp: the time of the last registration for this application - * @error: return location for a #GError or %NULL - * - * Sets the meta-data of application @name inside the list of - * applications that have registered a bookmark for @uri inside - * @bookmark. - * - * You should rarely use this function; use g_bookmark_file_add_application() - * and g_bookmark_file_remove_application() instead. - * - * @name can be any UTF-8 encoded string used to identify an - * application. - * @exec can have one of these two modifiers: "\%f", which will - * be expanded as the local file name retrieved from the bookmark's - * URI; "\%u", which will be expanded as the bookmark's URI. - * The expansion is done automatically when retrieving the stored - * command line using the g_bookmark_file_get_application_info() function. - * @count is the number of times the application has registered the - * bookmark; if is < 0, the current registration count will be increased - * by one, if is 0, the application with @name will be removed from - * the list of registered applications. - * @stamp is the Unix time of the last registration; if it is -1, the - * current time will be used. - * - * If you try to remove an application by setting its registration count to - * zero, and no bookmark for @uri is found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly, - * in the event that no application @name has registered a bookmark - * for @uri, %FALSE is returned and error is set to - * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark - * for @uri is found, one is created. - * - * Returns: %TRUE if the application's meta-data was successfully - * changed. - * Since: 2.12 - * Deprecated: 2.66: Use g_bookmark_file_set_application_info() instead, as - * `time_t` is deprecated due to the year 2038 problem. - */ - - -/** - * g_bookmark_file_set_application_info: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @name: an application's name - * @exec: an application's command line - * @count: the number of registrations done for this application - * @stamp: (nullable): the time of the last registration for this application, - * which may be %NULL if @count is 0 - * @error: return location for a #GError or %NULL - * - * Sets the meta-data of application @name inside the list of - * applications that have registered a bookmark for @uri inside - * @bookmark. - * - * You should rarely use this function; use g_bookmark_file_add_application() - * and g_bookmark_file_remove_application() instead. - * - * @name can be any UTF-8 encoded string used to identify an - * application. - * @exec can have one of these two modifiers: "\%f", which will - * be expanded as the local file name retrieved from the bookmark's - * URI; "\%u", which will be expanded as the bookmark's URI. - * The expansion is done automatically when retrieving the stored - * command line using the g_bookmark_file_get_application_info() function. - * @count is the number of times the application has registered the - * bookmark; if is < 0, the current registration count will be increased - * by one, if is 0, the application with @name will be removed from - * the list of registered applications. - * @stamp is the Unix time of the last registration. - * - * If you try to remove an application by setting its registration count to - * zero, and no bookmark for @uri is found, %FALSE is returned and - * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly, - * in the event that no application @name has registered a bookmark - * for @uri, %FALSE is returned and error is set to - * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark - * for @uri is found, one is created. - * - * Returns: %TRUE if the application's meta-data was successfully - * changed. - * Since: 2.66 - */ - - -/** - * g_bookmark_file_set_description: - * @bookmark: a #GBookmarkFile - * @uri: (nullable): a valid URI or %NULL - * @description: a string - * - * Sets @description as the description of the bookmark for @uri. - * - * If @uri is %NULL, the description of @bookmark is set. - * - * If a bookmark for @uri cannot be found then it is created. - * - * Since: 2.12 - */ - - -/** - * g_bookmark_file_set_groups: - * @bookmark: a #GBookmarkFile - * @uri: an item's URI - * @groups: (nullable) (array length=length) (element-type utf8): an array of - * group names, or %NULL to remove all groups - * @length: number of group name values in @groups - * - * Sets a list of group names for the item with URI @uri. Each previously - * set group name list is removed. - * - * If @uri cannot be found then an item for it is created. - * - * Since: 2.12 - */ - - -/** - * g_bookmark_file_set_icon: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @href: (nullable): the URI of the icon for the bookmark, or %NULL - * @mime_type: the MIME type of the icon for the bookmark - * - * Sets the icon for the bookmark for @uri. If @href is %NULL, unsets - * the currently set icon. @href can either be a full URL for the icon - * file or the icon name following the Icon Naming specification. - * - * If no bookmark for @uri is found one is created. - * - * Since: 2.12 - */ - - -/** - * g_bookmark_file_set_is_private: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @is_private: %TRUE if the bookmark should be marked as private - * - * Sets the private flag of the bookmark for @uri. - * - * If a bookmark for @uri cannot be found then it is created. - * - * Since: 2.12 - */ - - -/** - * g_bookmark_file_set_mime_type: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @mime_type: a MIME type - * - * Sets @mime_type as the MIME type of the bookmark for @uri. - * - * If a bookmark for @uri cannot be found then it is created. - * - * Since: 2.12 - */ - - -/** - * g_bookmark_file_set_modified: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @modified: a timestamp or -1 to use the current time - * - * Sets the last time the bookmark for @uri was last modified. - * - * If no bookmark for @uri is found then it is created. - * - * The "modified" time should only be set when the bookmark's meta-data - * was actually changed. Every function of #GBookmarkFile that - * modifies a bookmark also changes the modification time, except for - * g_bookmark_file_set_visited_date_time(). - * - * Since: 2.12 - * Deprecated: 2.66: Use g_bookmark_file_set_modified_date_time() instead, as - * `time_t` is deprecated due to the year 2038 problem. - */ - - -/** - * g_bookmark_file_set_modified_date_time: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @modified: a #GDateTime - * - * Sets the last time the bookmark for @uri was last modified. - * - * If no bookmark for @uri is found then it is created. - * - * The "modified" time should only be set when the bookmark's meta-data - * was actually changed. Every function of #GBookmarkFile that - * modifies a bookmark also changes the modification time, except for - * g_bookmark_file_set_visited_date_time(). - * - * Since: 2.66 - */ - - -/** - * g_bookmark_file_set_title: - * @bookmark: a #GBookmarkFile - * @uri: (nullable): a valid URI or %NULL - * @title: a UTF-8 encoded string - * - * Sets @title as the title of the bookmark for @uri inside the - * bookmark file @bookmark. - * - * If @uri is %NULL, the title of @bookmark is set. - * - * If a bookmark for @uri cannot be found then it is created. - * - * Since: 2.12 - */ - - -/** - * g_bookmark_file_set_visited: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @visited: a timestamp or -1 to use the current time - * - * Sets the time the bookmark for @uri was last visited. - * - * If no bookmark for @uri is found then it is created. - * - * The "visited" time should only be set if the bookmark was launched, - * either using the command line retrieved by g_bookmark_file_get_application_info() - * or by the default application for the bookmark's MIME type, retrieved - * using g_bookmark_file_get_mime_type(). Changing the "visited" time - * does not affect the "modified" time. - * - * Since: 2.12 - * Deprecated: 2.66: Use g_bookmark_file_set_visited_date_time() instead, as - * `time_t` is deprecated due to the year 2038 problem. - */ - - -/** - * g_bookmark_file_set_visited_date_time: - * @bookmark: a #GBookmarkFile - * @uri: a valid URI - * @visited: a #GDateTime - * - * Sets the time the bookmark for @uri was last visited. - * - * If no bookmark for @uri is found then it is created. - * - * The "visited" time should only be set if the bookmark was launched, - * either using the command line retrieved by g_bookmark_file_get_application_info() - * or by the default application for the bookmark's MIME type, retrieved - * using g_bookmark_file_get_mime_type(). Changing the "visited" time - * does not affect the "modified" time. - * - * Since: 2.66 - */ - - -/** - * g_bookmark_file_to_data: - * @bookmark: a #GBookmarkFile - * @length: (out) (optional): return location for the length of the returned string, or %NULL - * @error: return location for a #GError, or %NULL - * - * This function outputs @bookmark as a string. - * - * Returns: (transfer full) (array length=length) (element-type guint8): - * a newly allocated string holding the contents of the #GBookmarkFile - * Since: 2.12 - */ - - -/** - * g_bookmark_file_to_file: - * @bookmark: a #GBookmarkFile - * @filename: (type filename): path of the output file - * @error: return location for a #GError, or %NULL - * - * This function outputs @bookmark into a file. The write process is - * guaranteed to be atomic by using g_file_set_contents() internally. - * - * Returns: %TRUE if the file was successfully written. - * Since: 2.12 - */ - - -/** - * g_build_filename: - * @first_element: (type filename): the first element in the path - * @...: remaining elements in path, terminated by %NULL - * - * Creates a filename from a series of elements using the correct - * separator for filenames. - * - * On Unix, this function behaves identically to `g_build_path - * (G_DIR_SEPARATOR_S, first_element, ....)`. - * - * On Windows, it takes into account that either the backslash - * (`\` or slash (`/`) can be used as separator in filenames, but - * otherwise behaves as on UNIX. When file pathname separators need - * to be inserted, the one that last previously occurred in the - * parameters (reading from left to right) is used. - * - * No attempt is made to force the resulting filename to be an absolute - * path. If the first element is a relative path, the result will - * be a relative path. - * - * Returns: (type filename): a newly-allocated string that must be freed with - * g_free(). - */ - - -/** - * g_build_filename_valist: - * @first_element: (type filename): the first element in the path - * @args: va_list of remaining elements in path - * - * Behaves exactly like g_build_filename(), but takes the path elements - * as a va_list. This function is mainly meant for language bindings. - * - * Returns: (type filename): a newly-allocated string that must be freed - * with g_free(). - * Since: 2.56 - */ - - -/** - * g_build_filenamev: - * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated - * array of strings containing the path elements. - * - * Behaves exactly like g_build_filename(), but takes the path elements - * as a string array, instead of varargs. This function is mainly - * meant for language bindings. - * - * Returns: (type filename): a newly-allocated string that must be freed - * with g_free(). - * Since: 2.8 - */ - - -/** - * g_build_path: - * @separator: (type filename): a string used to separator the elements of the path. - * @first_element: (type filename): the first element in the path - * @...: remaining elements in path, terminated by %NULL - * - * Creates a path from a series of elements using @separator as the - * separator between elements. At the boundary between two elements, - * any trailing occurrences of separator in the first element, or - * leading occurrences of separator in the second element are removed - * and exactly one copy of the separator is inserted. - * - * Empty elements are ignored. - * - * The number of leading copies of the separator on the result is - * the same as the number of leading copies of the separator on - * the first non-empty element. - * - * The number of trailing copies of the separator on the result is - * the same as the number of trailing copies of the separator on - * the last non-empty element. (Determination of the number of - * trailing copies is done without stripping leading copies, so - * if the separator is `ABA`, then `ABABA` has 1 trailing copy.) - * - * However, if there is only a single non-empty element, and there - * are no characters in that element not part of the leading or - * trailing separators, then the result is exactly the original value - * of that element. - * - * Other than for determination of the number of leading and trailing - * copies of the separator, elements consisting only of copies - * of the separator are ignored. - * - * Returns: (type filename): a newly-allocated string that must be freed with - * g_free(). - */ - - -/** - * g_build_pathv: - * @separator: a string used to separator the elements of the path. - * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated - * array of strings containing the path elements. - * - * Behaves exactly like g_build_path(), but takes the path elements - * as a string array, instead of varargs. This function is mainly - * meant for language bindings. - * - * Returns: (type filename): a newly-allocated string that must be freed - * with g_free(). - * Since: 2.8 - */ - - -/** - * g_byte_array_append: - * @array: a #GByteArray - * @data: the byte data to be added - * @len: the number of bytes to add - * - * Adds the given bytes to the end of the #GByteArray. - * The array will grow in size automatically if necessary. - * - * Returns: the #GByteArray - */ - - -/** - * g_byte_array_free: - * @array: a #GByteArray - * @free_segment: if %TRUE the actual byte data is freed as well - * - * Frees the memory allocated by the #GByteArray. If @free_segment is - * %TRUE it frees the actual byte data. If the reference count of - * @array is greater than one, the #GByteArray wrapper is preserved but - * the size of @array will be set to zero. - * - * Returns: the element data if @free_segment is %FALSE, otherwise - * %NULL. The element data should be freed using g_free(). - */ - - -/** - * g_byte_array_free_to_bytes: - * @array: (transfer full): a #GByteArray - * - * Transfers the data from the #GByteArray into a new immutable #GBytes. - * - * The #GByteArray is freed unless the reference count of @array is greater - * than one, the #GByteArray wrapper is preserved but the size of @array - * will be set to zero. - * - * This is identical to using g_bytes_new_take() and g_byte_array_free() - * together. - * - * Since: 2.32 - * Returns: (transfer full): a new immutable #GBytes representing same - * byte data that was in the array - */ - - -/** - * g_byte_array_new: - * - * Creates a new #GByteArray with a reference count of 1. - * - * Returns: (transfer full): the new #GByteArray - */ - - -/** - * g_byte_array_new_take: - * @data: (transfer full) (array length=len): byte data for the array - * @len: length of @data - * - * Create byte array containing the data. The data will be owned by the array - * and will be freed with g_free(), i.e. it could be allocated using g_strdup(). - * - * Do not use it if @len is greater than %G_MAXUINT. #GByteArray - * stores the length of its data in #guint, which may be shorter than - * #gsize. - * - * Since: 2.32 - * Returns: (transfer full): a new #GByteArray - */ - - -/** - * g_byte_array_prepend: - * @array: a #GByteArray - * @data: the byte data to be added - * @len: the number of bytes to add - * - * Adds the given data to the start of the #GByteArray. - * The array will grow in size automatically if necessary. - * - * Returns: the #GByteArray - */ - - -/** - * g_byte_array_ref: - * @array: A #GByteArray - * - * Atomically increments the reference count of @array by one. - * This function is thread-safe and may be called from any thread. - * - * Returns: The passed in #GByteArray - * Since: 2.22 - */ - - -/** - * g_byte_array_remove_index: - * @array: a #GByteArray - * @index_: the index of the byte to remove - * - * Removes the byte at the given index from a #GByteArray. - * The following bytes are moved down one place. - * - * Returns: the #GByteArray - */ - - -/** - * g_byte_array_remove_index_fast: - * @array: a #GByteArray - * @index_: the index of the byte to remove - * - * Removes the byte at the given index from a #GByteArray. The last - * element in the array is used to fill in the space, so this function - * does not preserve the order of the #GByteArray. But it is faster - * than g_byte_array_remove_index(). - * - * Returns: the #GByteArray - */ - - -/** - * g_byte_array_remove_range: - * @array: a @GByteArray - * @index_: the index of the first byte to remove - * @length: the number of bytes to remove - * - * Removes the given number of bytes starting at the given index from a - * #GByteArray. The following elements are moved to close the gap. - * - * Returns: the #GByteArray - * Since: 2.4 - */ - - -/** - * g_byte_array_set_size: - * @array: a #GByteArray - * @length: the new size of the #GByteArray - * - * Sets the size of the #GByteArray, expanding it if necessary. - * - * Returns: the #GByteArray - */ - - -/** - * g_byte_array_sized_new: - * @reserved_size: number of bytes preallocated - * - * Creates a new #GByteArray with @reserved_size bytes preallocated. - * This avoids frequent reallocation, if you are going to add many - * bytes to the array. Note however that the size of the array is still - * 0. - * - * Returns: the new #GByteArray - */ - - -/** - * g_byte_array_sort: - * @array: a #GByteArray - * @compare_func: comparison function - * - * Sorts a byte array, using @compare_func which should be a - * qsort()-style comparison function (returns less than zero for first - * arg is less than second arg, zero for equal, greater than zero if - * first arg is greater than second arg). - * - * If two array elements compare equal, their order in the sorted array - * is undefined. If you want equal elements to keep their order (i.e. - * you want a stable sort) you can write a comparison function that, - * if two elements would otherwise compare equal, compares them by - * their addresses. - */ - - -/** - * g_byte_array_sort_with_data: - * @array: a #GByteArray - * @compare_func: comparison function - * @user_data: data to pass to @compare_func - * - * Like g_byte_array_sort(), but the comparison function takes an extra - * user data argument. - */ - - -/** - * g_byte_array_steal: - * @array: a #GByteArray. - * @len: (optional) (out): pointer to retrieve the number of - * elements of the original array - * - * Frees the data in the array and resets the size to zero, while - * the underlying array is preserved for use elsewhere and returned - * to the caller. - * - * Returns: (transfer full): the element data, which should be - * freed using g_free(). - * Since: 2.64 - */ - - -/** - * g_byte_array_unref: - * @array: A #GByteArray - * - * Atomically decrements the reference count of @array by one. If the - * reference count drops to 0, all memory allocated by the array is - * released. This function is thread-safe and may be called from any - * thread. - * - * Since: 2.22 - */ - - -/** - * g_bytes_compare: - * @bytes1: (type GLib.Bytes): a pointer to a #GBytes - * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1 - * - * Compares the two #GBytes values. - * - * This function can be used to sort GBytes instances in lexicographical order. - * - * If @bytes1 and @bytes2 have different length but the shorter one is a - * prefix of the longer one then the shorter one is considered to be less than - * the longer one. Otherwise the first byte where both differ is used for - * comparison. If @bytes1 has a smaller value at that position it is - * considered less, otherwise greater than @bytes2. - * - * Returns: a negative value if @bytes1 is less than @bytes2, a positive value - * if @bytes1 is greater than @bytes2, and zero if @bytes1 is equal to - * @bytes2 - * Since: 2.32 - */ - - -/** - * g_bytes_equal: - * @bytes1: (type GLib.Bytes): a pointer to a #GBytes - * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1 - * - * Compares the two #GBytes values being pointed to and returns - * %TRUE if they are equal. - * - * This function can be passed to g_hash_table_new() as the @key_equal_func - * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. - * - * Returns: %TRUE if the two keys match. - * Since: 2.32 - */ - - -/** - * g_bytes_get_data: - * @bytes: a #GBytes - * @size: (out) (optional): location to return size of byte data - * - * Get the byte data in the #GBytes. This data should not be modified. - * - * This function will always return the same pointer for a given #GBytes. - * - * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes - * may represent an empty string with @data non-%NULL and @size as 0. %NULL will - * not be returned if @size is non-zero. - * - * Returns: (transfer none) (array length=size) (element-type guint8) (nullable): - * a pointer to the byte data, or %NULL - * Since: 2.32 - */ - - -/** - * g_bytes_get_region: - * @bytes: a #GBytes - * @element_size: a non-zero element size - * @offset: an offset to the start of the region within the @bytes - * @n_elements: the number of elements in the region - * - * Gets a pointer to a region in @bytes. - * - * The region starts at @offset many bytes from the start of the data - * and contains @n_elements many elements of @element_size size. - * - * @n_elements may be zero, but @element_size must always be non-zero. - * Ideally, @element_size is a static constant (eg: sizeof a struct). - * - * This function does careful bounds checking (including checking for - * arithmetic overflows) and returns a non-%NULL pointer if the - * specified region lies entirely within the @bytes. If the region is - * in some way out of range, or if an overflow has occurred, then %NULL - * is returned. - * - * Note: it is possible to have a valid zero-size region. In this case, - * the returned pointer will be equal to the base pointer of the data of - * @bytes, plus @offset. This will be non-%NULL except for the case - * where @bytes itself was a zero-sized region. Since it is unlikely - * that you will be using this function to check for a zero-sized region - * in a zero-sized @bytes, %NULL effectively always means "error". - * - * Returns: (nullable): the requested region, or %NULL in case of an error - * Since: 2.70 - */ - - -/** - * g_bytes_get_size: - * @bytes: a #GBytes - * - * Get the size of the byte data in the #GBytes. - * - * This function will always return the same value for a given #GBytes. - * - * Returns: the size - * Since: 2.32 - */ - - -/** - * g_bytes_hash: - * @bytes: (type GLib.Bytes): a pointer to a #GBytes key - * - * Creates an integer hash code for the byte data in the #GBytes. - * - * This function can be passed to g_hash_table_new() as the @key_hash_func - * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable. - * - * Returns: a hash value corresponding to the key. - * Since: 2.32 - */ - - -/** - * g_bytes_new: - * @data: (transfer none) (array length=size) (element-type guint8) (nullable): - * the data to be used for the bytes - * @size: the size of @data - * - * Creates a new #GBytes from @data. - * - * @data is copied. If @size is 0, @data may be %NULL. - * - * Returns: (transfer full): a new #GBytes - * Since: 2.32 - */ - - -/** - * g_bytes_new_from_bytes: - * @bytes: a #GBytes - * @offset: offset which subsection starts at - * @length: length of subsection - * - * Creates a #GBytes which is a subsection of another #GBytes. The @offset + - * @length may not be longer than the size of @bytes. - * - * A reference to @bytes will be held by the newly created #GBytes until - * the byte data is no longer needed. - * - * Since 2.56, if @offset is 0 and @length matches the size of @bytes, then - * @bytes will be returned with the reference count incremented by 1. If @bytes - * is a slice of another #GBytes, then the resulting #GBytes will reference - * the same #GBytes instead of @bytes. This allows consumers to simplify the - * usage of #GBytes when asynchronously writing to streams. - * - * Returns: (transfer full): a new #GBytes - * Since: 2.32 - */ - - -/** - * g_bytes_new_static: (skip) - * @data: (transfer full) (array length=size) (element-type guint8) (nullable): - * the data to be used for the bytes - * @size: the size of @data - * - * Creates a new #GBytes from static data. - * - * @data must be static (ie: never modified or freed). It may be %NULL if @size - * is 0. - * - * Returns: (transfer full): a new #GBytes - * Since: 2.32 - */ - - -/** - * g_bytes_new_take: - * @data: (transfer full) (array length=size) (element-type guint8) (nullable): - * the data to be used for the bytes - * @size: the size of @data - * - * Creates a new #GBytes from @data. - * - * After this call, @data belongs to the bytes and may no longer be - * modified by the caller. g_free() will be called on @data when the - * bytes is no longer in use. Because of this @data must have been created by - * a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many - * functions that wrap these calls (such as g_new(), g_strdup(), etc). - * - * For creating #GBytes with memory from other allocators, see - * g_bytes_new_with_free_func(). - * - * @data may be %NULL if @size is 0. - * - * Returns: (transfer full): a new #GBytes - * Since: 2.32 - */ - - -/** - * g_bytes_new_with_free_func: (skip) - * @data: (array length=size) (element-type guint8) (nullable): - * the data to be used for the bytes - * @size: the size of @data - * @free_func: the function to call to release the data - * @user_data: data to pass to @free_func - * - * Creates a #GBytes from @data. - * - * When the last reference is dropped, @free_func will be called with the - * @user_data argument. - * - * @data must not be modified after this call is made until @free_func has - * been called to indicate that the bytes is no longer in use. - * - * @data may be %NULL if @size is 0. - * - * Returns: (transfer full): a new #GBytes - * Since: 2.32 - */ - - -/** - * g_bytes_ref: - * @bytes: a #GBytes - * - * Increase the reference count on @bytes. - * - * Returns: the #GBytes - * Since: 2.32 - */ - - -/** - * g_bytes_unref: - * @bytes: (nullable): a #GBytes - * - * Releases a reference on @bytes. This may result in the bytes being - * freed. If @bytes is %NULL, it will return immediately. - * - * Since: 2.32 - */ - - -/** - * g_bytes_unref_to_array: - * @bytes: (transfer full): a #GBytes - * - * Unreferences the bytes, and returns a new mutable #GByteArray containing - * the same byte data. - * - * As an optimization, the byte data is transferred to the array without copying - * if this was the last reference to bytes and bytes was created with - * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all - * other cases the data is copied. - * - * Do not use it if @bytes contains more than %G_MAXUINT - * bytes. #GByteArray stores the length of its data in #guint, which - * may be shorter than #gsize, that @bytes is using. - * - * Returns: (transfer full): a new mutable #GByteArray containing the same byte data - * Since: 2.32 - */ - - -/** - * g_bytes_unref_to_data: - * @bytes: (transfer full): a #GBytes - * @size: (out): location to place the length of the returned data - * - * Unreferences the bytes, and returns a pointer the same byte data - * contents. - * - * As an optimization, the byte data is returned without copying if this was - * the last reference to bytes and bytes was created with g_bytes_new(), - * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the - * data is copied. - * - * Returns: (transfer full) (array length=size) (element-type guint8) (not nullable): a pointer to the same byte data, which should be - * freed with g_free() - * Since: 2.32 - */ - - -/** - * g_canonicalize_filename: - * @filename: (type filename): the name of the file - * @relative_to: (type filename) (nullable): the relative directory, or %NULL - * to use the current working directory - * - * Gets the canonical file name from @filename. All triple slashes are turned into - * single slashes, and all `..` and `.`s resolved against @relative_to. - * - * Symlinks are not followed, and the returned path is guaranteed to be absolute. - * - * If @filename is an absolute path, @relative_to is ignored. Otherwise, - * @relative_to will be prepended to @filename to make it absolute. @relative_to - * must be an absolute path, or %NULL. If @relative_to is %NULL, it'll fallback - * to g_get_current_dir(). - * - * This function never fails, and will canonicalize file paths even if they don't - * exist. - * - * No file system I/O is done. - * - * Returns: (type filename) (transfer full): a newly allocated string with the - * canonical file path - * Since: 2.58 - */ - - -/** - * g_chdir: - * @path: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * - * A wrapper for the POSIX chdir() function. The function changes the - * current directory of the process to @path. - * - * See your C library manual for more details about chdir(). - * - * Returns: 0 on success, -1 if an error occurred. - * Since: 2.8 - */ - - -/** - * g_checksum_copy: - * @checksum: the #GChecksum to copy - * - * Copies a #GChecksum. If @checksum has been closed, by calling - * g_checksum_get_string() or g_checksum_get_digest(), the copied - * checksum will be closed as well. - * - * Returns: (transfer full): the copy of the passed #GChecksum. Use - * g_checksum_free() when finished using it. - * Since: 2.16 - */ - - -/** - * g_checksum_free: - * @checksum: a #GChecksum - * - * Frees the memory allocated for @checksum. - * - * Since: 2.16 - */ - - -/** - * g_checksum_get_digest: (skip) - * @checksum: a #GChecksum - * @buffer: (array length=digest_len): output buffer - * @digest_len: (inout): an inout parameter. The caller initializes it to the size of @buffer. - * After the call it contains the length of the digest. - * - * Gets the digest from @checksum as a raw binary vector and places it - * into @buffer. The size of the digest depends on the type of checksum. - * - * Once this function has been called, the #GChecksum is closed and can - * no longer be updated with g_checksum_update(). - * - * Since: 2.16 - */ - - -/** - * g_checksum_get_string: - * @checksum: a #GChecksum - * - * Gets the digest as a hexadecimal string. - * - * Once this function has been called the #GChecksum can no longer be - * updated with g_checksum_update(). - * - * The hexadecimal characters will be lower case. - * - * Returns: the hexadecimal representation of the checksum. The - * returned string is owned by the checksum and should not be modified - * or freed. - * Since: 2.16 - */ - - -/** - * g_checksum_new: - * @checksum_type: the desired type of checksum - * - * Creates a new #GChecksum, using the checksum algorithm @checksum_type. - * If the @checksum_type is not known, %NULL is returned. - * A #GChecksum can be used to compute the checksum, or digest, of an - * arbitrary binary blob, using different hashing algorithms. - * - * A #GChecksum works by feeding a binary blob through g_checksum_update() - * until there is data to be checked; the digest can then be extracted - * using g_checksum_get_string(), which will return the checksum as a - * hexadecimal string; or g_checksum_get_digest(), which will return a - * vector of raw bytes. Once either g_checksum_get_string() or - * g_checksum_get_digest() have been called on a #GChecksum, the checksum - * will be closed and it won't be possible to call g_checksum_update() - * on it anymore. - * - * Returns: (transfer full) (nullable): the newly created #GChecksum, or %NULL. - * Use g_checksum_free() to free the memory allocated by it. - * Since: 2.16 - */ - - -/** - * g_checksum_reset: - * @checksum: the #GChecksum to reset - * - * Resets the state of the @checksum back to its initial state. - * - * Since: 2.18 - */ - - -/** - * g_checksum_type_get_length: - * @checksum_type: a #GChecksumType - * - * Gets the length in bytes of digests of type @checksum_type - * - * Returns: the checksum length, or -1 if @checksum_type is - * not supported. - * Since: 2.16 - */ - - -/** - * g_checksum_update: - * @checksum: a #GChecksum - * @data: (array length=length) (element-type guint8): buffer used to compute the checksum - * @length: size of the buffer, or -1 if it is a null-terminated string. - * - * Feeds @data into an existing #GChecksum. The checksum must still be - * open, that is g_checksum_get_string() or g_checksum_get_digest() must - * not have been called on @checksum. - * - * Since: 2.16 - */ - - -/** - * g_child_watch_add: - * @pid: process id to watch. On POSIX the positive pid of a child - * process. On Windows a handle for a process (which doesn't have - * to be a child). - * @function: function to call - * @data: data to pass to @function - * - * Sets a function to be called when the child indicated by @pid - * exits, at a default priority, %G_PRIORITY_DEFAULT. - * - * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() - * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to - * the spawn function for the child watching to work. - * - * Note that on platforms where #GPid must be explicitly closed - * (see g_spawn_close_pid()) @pid must not be closed while the - * source is still active. Typically, you will want to call - * g_spawn_close_pid() in the callback function for the source. - * - * GLib supports only a single callback per process id. - * On POSIX platforms, the same restrictions mentioned for - * g_child_watch_source_new() apply to this function. - * - * This internally creates a main loop source using - * g_child_watch_source_new() and attaches it to the main loop context - * using g_source_attach(). You can do these steps manually if you - * need greater control. - * - * Returns: the ID (greater than 0) of the event source. - * Since: 2.4 - */ - - -/** - * g_child_watch_add_full: (rename-to g_child_watch_add) - * @priority: the priority of the idle source. Typically this will be in the - * range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. - * @pid: process to watch. On POSIX the positive pid of a child process. On - * Windows a handle for a process (which doesn't have to be a child). - * @function: function to call - * @data: data to pass to @function - * @notify: (nullable): function to call when the idle is removed, or %NULL - * - * Sets a function to be called when the child indicated by @pid - * exits, at the priority @priority. - * - * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() - * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to - * the spawn function for the child watching to work. - * - * In many programs, you will want to call g_spawn_check_wait_status() - * in the callback to determine whether or not the child exited - * successfully. - * - * Also, note that on platforms where #GPid must be explicitly closed - * (see g_spawn_close_pid()) @pid must not be closed while the source - * is still active. Typically, you should invoke g_spawn_close_pid() - * in the callback function for the source. - * - * GLib supports only a single callback per process id. - * On POSIX platforms, the same restrictions mentioned for - * g_child_watch_source_new() apply to this function. - * - * This internally creates a main loop source using - * g_child_watch_source_new() and attaches it to the main loop context - * using g_source_attach(). You can do these steps manually if you - * need greater control. - * - * Returns: the ID (greater than 0) of the event source. - * Since: 2.4 - */ - - -/** - * g_child_watch_source_new: - * @pid: process to watch. On POSIX the positive pid of a child process. On - * Windows a handle for a process (which doesn't have to be a child). - * - * Creates a new child_watch source. - * - * The source will not initially be associated with any #GMainContext - * and must be added to one with g_source_attach() before it will be - * executed. - * - * Note that child watch sources can only be used in conjunction with - * `g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used. - * - * Note that on platforms where #GPid must be explicitly closed - * (see g_spawn_close_pid()) @pid must not be closed while the - * source is still active. Typically, you will want to call - * g_spawn_close_pid() in the callback function for the source. - * - * On POSIX platforms, the following restrictions apply to this API - * due to limitations in POSIX process interfaces: - * - * * @pid must be a child of this process - * * @pid must be positive - * * the application must not call `waitpid` with a non-positive - * first argument, for instance in another thread - * * the application must not wait for @pid to exit by any other - * mechanism, including `waitpid(pid, ...)` or a second child-watch - * source for the same @pid - * * the application must not ignore `SIGCHLD` - * - * If any of those conditions are not met, this and related APIs will - * not work correctly. This can often be diagnosed via a GLib warning - * stating that `ECHILD` was received by `waitpid`. - * - * Calling `waitpid` for specific processes other than @pid remains a - * valid thing to do. - * - * Returns: the newly-created child watch source - * Since: 2.4 - */ - - -/** - * g_chmod: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * @mode: as in chmod() - * - * A wrapper for the POSIX chmod() function. The chmod() function is - * used to set the permissions of a file system object. - * - * On Windows the file protection mechanism is not at all POSIX-like, - * and the underlying chmod() function in the C library just sets or - * clears the FAT-style READONLY attribute. It does not touch any - * ACL. Software that needs to manage file permissions on Windows - * exactly should use the Win32 API. - * - * See your C library manual for more details about chmod(). - * - * Returns: 0 if the operation succeeded, -1 on error - * Since: 2.8 - */ - - -/** - * g_clear_error: - * @err: a #GError return location - * - * If @err or *@err is %NULL, does nothing. Otherwise, - * calls g_error_free() on *@err and sets *@err to %NULL. - */ - - -/** - * g_clear_handle_id: (skip) - * @tag_ptr: (not nullable): a pointer to the handler ID - * @clear_func: (not nullable): the function to call to clear the handler - * - * Clears a numeric handler, such as a #GSource ID. - * - * @tag_ptr must be a valid pointer to the variable holding the handler. - * - * If the ID is zero then this function does nothing. - * Otherwise, clear_func() is called with the ID as a parameter, and the tag is - * set to zero. - * - * A macro is also included that allows this function to be used without - * pointer casts. - * - * Since: 2.56 - */ - - -/** - * g_clear_list: (skip) - * @list_ptr: (not nullable): a #GList return location - * @destroy: (nullable): the function to pass to g_list_free_full() or %NULL to not free elements - * - * Clears a pointer to a #GList, freeing it and, optionally, freeing its elements using @destroy. - * - * @list_ptr must be a valid pointer. If @list_ptr points to a null #GList, this does nothing. - * - * Since: 2.64 - */ - - -/** - * g_clear_pointer: (skip) - * @pp: (not nullable): a pointer to a variable, struct member etc. holding a - * pointer - * @destroy: a function to which a gpointer can be passed, to destroy *@pp - * - * Clears a reference to a variable. - * - * @pp must not be %NULL. - * - * If the reference is %NULL then this function does nothing. - * Otherwise, the variable is destroyed using @destroy and the - * pointer is set to %NULL. - * - * A macro is also included that allows this function to be used without - * pointer casts. This will mask any warnings about incompatible function types - * or calling conventions, so you must ensure that your @destroy function is - * compatible with being called as `GDestroyNotify` using the standard calling - * convention for the platform that GLib was compiled for; otherwise the program - * will experience undefined behaviour. - * - * Since: 2.34 - */ - - -/** - * g_clear_slist: (skip) - * @slist_ptr: (not nullable): a #GSList return location - * @destroy: (nullable): the function to pass to g_slist_free_full() or %NULL to not free elements - * - * Clears a pointer to a #GSList, freeing it and, optionally, freeing its elements using @destroy. - * - * @slist_ptr must be a valid pointer. If @slist_ptr points to a null #GSList, this does nothing. - * - * Since: 2.64 - */ - - -/** - * g_close: - * @fd: A file descriptor - * @error: a #GError - * - * This wraps the close() call; in case of error, %errno will be - * preserved, but the error will also be stored as a #GError in @error. - * - * Besides using #GError, there is another major reason to prefer this - * function over the call provided by the system; on Unix, it will - * attempt to correctly handle %EINTR, which has platform-specific - * semantics. - * - * Returns: %TRUE on success, %FALSE if there was an error. - * Since: 2.36 - */ - - -/** - * g_compute_checksum_for_bytes: - * @checksum_type: a #GChecksumType - * @data: binary blob to compute the digest of - * - * Computes the checksum for a binary @data. This is a - * convenience wrapper for g_checksum_new(), g_checksum_get_string() - * and g_checksum_free(). - * - * The hexadecimal string returned will be in lower case. - * - * Returns: (transfer full) (nullable): the digest of the binary data as a - * string in hexadecimal, or %NULL if g_checksum_new() fails for - * @checksum_type. The returned string should be freed with g_free() when - * done using it. - * Since: 2.34 - */ - - -/** - * g_compute_checksum_for_data: - * @checksum_type: a #GChecksumType - * @data: (array length=length) (element-type guint8): binary blob to compute the digest of - * @length: length of @data - * - * Computes the checksum for a binary @data of @length. This is a - * convenience wrapper for g_checksum_new(), g_checksum_get_string() - * and g_checksum_free(). - * - * The hexadecimal string returned will be in lower case. - * - * Returns: (transfer full) (nullable): the digest of the binary data as a - * string in hexadecimal, or %NULL if g_checksum_new() fails for - * @checksum_type. The returned string should be freed with g_free() when - * done using it. - * Since: 2.16 - */ - - -/** - * g_compute_checksum_for_string: - * @checksum_type: a #GChecksumType - * @str: the string to compute the checksum of - * @length: the length of the string, or -1 if the string is null-terminated. - * - * Computes the checksum of a string. - * - * The hexadecimal string returned will be in lower case. - * - * Returns: (transfer full) (nullable): the checksum as a hexadecimal string, - * or %NULL if g_checksum_new() fails for @checksum_type. The returned string - * should be freed with g_free() when done using it. - * Since: 2.16 - */ - - -/** - * g_compute_hmac_for_bytes: - * @digest_type: a #GChecksumType to use for the HMAC - * @key: the key to use in the HMAC - * @data: binary blob to compute the HMAC of - * - * Computes the HMAC for a binary @data. This is a - * convenience wrapper for g_hmac_new(), g_hmac_get_string() - * and g_hmac_unref(). - * - * The hexadecimal string returned will be in lower case. - * - * Returns: the HMAC of the binary data as a string in hexadecimal. - * The returned string should be freed with g_free() when done using it. - * Since: 2.50 - */ - - -/** - * g_compute_hmac_for_data: - * @digest_type: a #GChecksumType to use for the HMAC - * @key: (array length=key_len): the key to use in the HMAC - * @key_len: the length of the key - * @data: (array length=length): binary blob to compute the HMAC of - * @length: length of @data - * - * Computes the HMAC for a binary @data of @length. This is a - * convenience wrapper for g_hmac_new(), g_hmac_get_string() - * and g_hmac_unref(). - * - * The hexadecimal string returned will be in lower case. - * - * Returns: the HMAC of the binary data as a string in hexadecimal. - * The returned string should be freed with g_free() when done using it. - * Since: 2.30 - */ - - -/** - * g_compute_hmac_for_string: - * @digest_type: a #GChecksumType to use for the HMAC - * @key: (array length=key_len): the key to use in the HMAC - * @key_len: the length of the key - * @str: the string to compute the HMAC for - * @length: the length of the string, or -1 if the string is nul-terminated - * - * Computes the HMAC for a string. - * - * The hexadecimal string returned will be in lower case. - * - * Returns: the HMAC as a hexadecimal string. - * The returned string should be freed with g_free() - * when done using it. - * Since: 2.30 - */ - - -/** - * g_cond_broadcast: - * @cond: a #GCond - * - * If threads are waiting for @cond, all of them are unblocked. - * If no threads are waiting for @cond, this function has no effect. - * It is good practice to lock the same mutex as the waiting threads - * while calling this function, though not required. - */ - - -/** - * g_cond_clear: - * @cond: an initialised #GCond - * - * Frees the resources allocated to a #GCond with g_cond_init(). - * - * This function should not be used with a #GCond that has been - * statically allocated. - * - * Calling g_cond_clear() for a #GCond on which threads are - * blocking leads to undefined behaviour. - * - * Since: 2.32 - */ - - -/** - * g_cond_init: - * @cond: an uninitialized #GCond - * - * Initialises a #GCond so that it can be used. - * - * This function is useful to initialise a #GCond that has been - * allocated as part of a larger structure. It is not necessary to - * initialise a #GCond that has been statically allocated. - * - * To undo the effect of g_cond_init() when a #GCond is no longer - * needed, use g_cond_clear(). - * - * Calling g_cond_init() on an already-initialised #GCond leads - * to undefined behaviour. - * - * Since: 2.32 - */ - - -/** - * g_cond_signal: - * @cond: a #GCond - * - * If threads are waiting for @cond, at least one of them is unblocked. - * If no threads are waiting for @cond, this function has no effect. - * It is good practice to hold the same lock as the waiting thread - * while calling this function, though not required. - */ - - -/** - * g_cond_wait: - * @cond: a #GCond - * @mutex: a #GMutex that is currently locked - * - * Atomically releases @mutex and waits until @cond is signalled. - * When this function returns, @mutex is locked again and owned by the - * calling thread. - * - * When using condition variables, it is possible that a spurious wakeup - * may occur (ie: g_cond_wait() returns even though g_cond_signal() was - * not called). It's also possible that a stolen wakeup may occur. - * This is when g_cond_signal() is called, but another thread acquires - * @mutex before this thread and modifies the state of the program in - * such a way that when g_cond_wait() is able to return, the expected - * condition is no longer met. - * - * For this reason, g_cond_wait() must always be used in a loop. See - * the documentation for #GCond for a complete example. - */ - - -/** - * g_cond_wait_until: - * @cond: a #GCond - * @mutex: a #GMutex that is currently locked - * @end_time: the monotonic time to wait until - * - * Waits until either @cond is signalled or @end_time has passed. - * - * As with g_cond_wait() it is possible that a spurious or stolen wakeup - * could occur. For that reason, waiting on a condition variable should - * always be in a loop, based on an explicitly-checked predicate. - * - * %TRUE is returned if the condition variable was signalled (or in the - * case of a spurious wakeup). %FALSE is returned if @end_time has - * passed. - * - * The following code shows how to correctly perform a timed wait on a - * condition variable (extending the example presented in the - * documentation for #GCond): - * - * |[ - * gpointer - * pop_data_timed (void) - * { - * gint64 end_time; - * gpointer data; - * - * g_mutex_lock (&data_mutex); - * - * end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND; - * while (!current_data) - * if (!g_cond_wait_until (&data_cond, &data_mutex, end_time)) - * { - * // timeout has passed. - * g_mutex_unlock (&data_mutex); - * return NULL; - * } - * - * // there is data for us - * data = current_data; - * current_data = NULL; - * - * g_mutex_unlock (&data_mutex); - * - * return data; - * } - * ]| - * - * Notice that the end time is calculated once, before entering the - * loop and reused. This is the motivation behind the use of absolute - * time on this API -- if a relative time of 5 seconds were passed - * directly to the call and a spurious wakeup occurred, the program would - * have to start over waiting again (which would lead to a total wait - * time of more than 5 seconds). - * - * Returns: %TRUE on a signal, %FALSE on a timeout - * Since: 2.32 - */ - - -/** - * g_convert: - * @str: (array length=len) (element-type guint8): - * the string to convert. - * @len: the length of the string in bytes, or -1 if the string is - * nul-terminated (Note that some encodings may allow nul - * bytes to occur inside strings. In that case, using -1 - * for the @len parameter is unsafe) - * @to_codeset: name of character set into which to convert @str - * @from_codeset: character set of @str. - * @bytes_read: (out) (optional): location to store the number of bytes in - * the input string that were successfully converted, or %NULL. - * Even if the conversion was successful, this may be - * less than @len if there were partial characters - * at the end of the input. If the error - * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value - * stored will be the byte offset after the last valid - * input sequence. - * @bytes_written: (out) (optional): the number of bytes stored in - * the output buffer (not including the terminating nul). - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError may occur. - * - * Converts a string from one character set to another. - * - * Note that you should use g_iconv() for streaming conversions. - * Despite the fact that @bytes_read can return information about partial - * characters, the g_convert_... functions are not generally suitable - * for streaming. If the underlying converter maintains internal state, - * then this won't be preserved across successive calls to g_convert(), - * g_convert_with_iconv() or g_convert_with_fallback(). (An example of - * this is the GNU C converter for CP1255 which does not emit a base - * character until it knows that the next character is not a mark that - * could combine with the base character.) - * - * Using extensions such as "//TRANSLIT" may not work (or may not work - * well) on many platforms. Consider using g_str_to_ascii() instead. - * - * Returns: (array length=bytes_written) (element-type guint8) (transfer full): - * If the conversion was successful, a newly allocated buffer - * containing the converted string, which must be freed with g_free(). - * Otherwise %NULL and @error will be set. - */ - - -/** - * g_convert_with_fallback: - * @str: (array length=len) (element-type guint8): - * the string to convert. - * @len: the length of the string in bytes, or -1 if the string is - * nul-terminated (Note that some encodings may allow nul - * bytes to occur inside strings. In that case, using -1 - * for the @len parameter is unsafe) - * @to_codeset: name of character set into which to convert @str - * @from_codeset: character set of @str. - * @fallback: UTF-8 string to use in place of characters not - * present in the target encoding. (The string must be - * representable in the target encoding). - * If %NULL, characters not in the target encoding will - * be represented as Unicode escapes \uxxxx or \Uxxxxyyyy. - * @bytes_read: (out) (optional): location to store the number of bytes in - * the input string that were successfully converted, or %NULL. - * Even if the conversion was successful, this may be - * less than @len if there were partial characters - * at the end of the input. - * @bytes_written: (out) (optional): the number of bytes stored in - * the output buffer (not including the terminating nul). - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError may occur. - * - * Converts a string from one character set to another, possibly - * including fallback sequences for characters not representable - * in the output. Note that it is not guaranteed that the specification - * for the fallback sequences in @fallback will be honored. Some - * systems may do an approximate conversion from @from_codeset - * to @to_codeset in their iconv() functions, - * in which case GLib will simply return that approximate conversion. - * - * Note that you should use g_iconv() for streaming conversions. - * Despite the fact that @bytes_read can return information about partial - * characters, the g_convert_... functions are not generally suitable - * for streaming. If the underlying converter maintains internal state, - * then this won't be preserved across successive calls to g_convert(), - * g_convert_with_iconv() or g_convert_with_fallback(). (An example of - * this is the GNU C converter for CP1255 which does not emit a base - * character until it knows that the next character is not a mark that - * could combine with the base character.) - * - * Returns: (array length=bytes_written) (element-type guint8) (transfer full): - * If the conversion was successful, a newly allocated buffer - * containing the converted string, which must be freed with g_free(). - * Otherwise %NULL and @error will be set. - */ - - -/** - * g_convert_with_iconv: (skip) - * @str: (array length=len) (element-type guint8): - * the string to convert. - * @len: the length of the string in bytes, or -1 if the string is - * nul-terminated (Note that some encodings may allow nul - * bytes to occur inside strings. In that case, using -1 - * for the @len parameter is unsafe) - * @converter: conversion descriptor from g_iconv_open() - * @bytes_read: (out) (optional): location to store the number of bytes in - * the input string that were successfully converted, or %NULL. - * Even if the conversion was successful, this may be - * less than @len if there were partial characters - * at the end of the input. If the error - * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value - * stored will be the byte offset after the last valid - * input sequence. - * @bytes_written: (out) (optional): the number of bytes stored in - * the output buffer (not including the terminating nul). - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError may occur. - * - * Converts a string from one character set to another. - * - * Note that you should use g_iconv() for streaming conversions. - * Despite the fact that @bytes_read can return information about partial - * characters, the g_convert_... functions are not generally suitable - * for streaming. If the underlying converter maintains internal state, - * then this won't be preserved across successive calls to g_convert(), - * g_convert_with_iconv() or g_convert_with_fallback(). (An example of - * this is the GNU C converter for CP1255 which does not emit a base - * character until it knows that the next character is not a mark that - * could combine with the base character.) - * - * Characters which are valid in the input character set, but which have no - * representation in the output character set will result in a - * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error. This is in contrast to the iconv() - * specification, which leaves this behaviour implementation defined. Note that - * this is the same error code as is returned for an invalid byte sequence in - * the input character set. To get defined behaviour for conversion of - * unrepresentable characters, use g_convert_with_fallback(). - * - * Returns: (array length=bytes_written) (element-type guint8) (transfer full): - * If the conversion was successful, a newly allocated buffer - * containing the converted string, which must be freed with - * g_free(). Otherwise %NULL and @error will be set. - */ - - -/** - * g_creat: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * @mode: as in creat() - * - * A wrapper for the POSIX creat() function. The creat() function is - * used to convert a pathname into a file descriptor, creating a file - * if necessary. - * - * On POSIX systems file descriptors are implemented by the operating - * system. On Windows, it's the C library that implements creat() and - * file descriptors. The actual Windows API for opening files is - * different, see MSDN documentation for CreateFile(). The Win32 API - * uses file handles, which are more randomish integers, not small - * integers like file descriptors. - * - * Because file descriptors are specific to the C library on Windows, - * the file descriptor returned by this function makes sense only to - * functions in the same C library. Thus if the GLib-using code uses a - * different C library than GLib does, the file descriptor returned by - * this function cannot be passed to C library functions like write() - * or read(). - * - * See your C library manual for more details about creat(). - * - * Returns: a new file descriptor, or -1 if an error occurred. - * The return value can be used exactly like the return value - * from creat(). - * Since: 2.8 - */ - - -/** - * g_critical: - * @...: format string, followed by parameters to insert - * into the format string (as with printf()) - * - * Logs a "critical warning" (%G_LOG_LEVEL_CRITICAL). - * - * Critical warnings are intended to be used in the event of an error - * that originated in the current process (a programmer error). - * Logging of a critical error is by definition an indication of a bug - * somewhere in the current program (or its libraries). - * - * g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and - * g_return_val_if_reached() log at %G_LOG_LEVEL_CRITICAL. - * - * You can make critical warnings fatal at runtime by - * setting the `G_DEBUG` environment variable (see - * [Running GLib Applications](glib-running.html)): - * - * |[ - * G_DEBUG=fatal-warnings gdb ./my-program - * ]| - * - * You can also use g_log_set_always_fatal(). - * - * Any unrelated failures can be skipped over in - * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. - * - * The message should typically *not* be translated to the - * user's language. - * - * If g_log_default_handler() is used as the log handler function, a new-line - * character will automatically be appended to @..., and need not be entered - * manually. - * - * If structured logging is enabled, this will use g_log_structured(); - * otherwise it will use g_log(). See - * [Using Structured Logging][using-structured-logging]. - */ - - -/** - * g_datalist_clear: (skip) - * @datalist: a datalist. - * - * Frees all the data elements of the datalist. - * The data elements' destroy functions are called - * if they have been set. - */ - - -/** - * g_datalist_foreach: - * @datalist: a datalist. - * @func: (scope call): the function to call for each data element. - * @user_data: (closure): user data to pass to the function. - * - * Calls the given function for each data element of the datalist. The - * function is called with each data element's #GQuark id and data, - * together with the given @user_data parameter. Note that this - * function is NOT thread-safe. So unless @datalist can be protected - * from any modifications during invocation of this function, it should - * not be called. - * - * @func can make changes to @datalist, but the iteration will not - * reflect changes made during the g_datalist_foreach() call, other - * than skipping over elements that are removed. - */ - - -/** - * g_datalist_get_data: - * @datalist: a datalist. - * @key: the string identifying a data element. - * - * Gets a data element, using its string identifier. This is slower than - * g_datalist_id_get_data() because it compares strings. - * - * Returns: (transfer none) (nullable): the data element, or %NULL if it - * is not found. - */ - - -/** - * g_datalist_get_flags: - * @datalist: pointer to the location that holds a list - * - * Gets flags values packed in together with the datalist. - * See g_datalist_set_flags(). - * - * Returns: the flags of the datalist - * Since: 2.8 - */ - - -/** - * g_datalist_id_dup_data: (skip) - * @datalist: location of a datalist - * @key_id: the #GQuark identifying a data element - * @dup_func: (nullable) (scope call): function to duplicate the old value - * @user_data: (closure): passed as user_data to @dup_func - * - * This is a variant of g_datalist_id_get_data() which - * returns a 'duplicate' of the value. @dup_func defines the - * meaning of 'duplicate' in this context, it could e.g. - * take a reference on a ref-counted object. - * - * If the @key_id is not set in the datalist then @dup_func - * will be called with a %NULL argument. - * - * Note that @dup_func is called while the datalist is locked, so it - * is not allowed to read or modify the datalist. - * - * This function can be useful to avoid races when multiple - * threads are using the same datalist and the same key. - * - * Returns: (nullable): the result of calling @dup_func on the value - * associated with @key_id in @datalist, or %NULL if not set. - * If @dup_func is %NULL, the value is returned unmodified. - * Since: 2.34 - */ - - -/** - * g_datalist_id_get_data: - * @datalist: a datalist. - * @key_id: the #GQuark identifying a data element. - * - * Retrieves the data element corresponding to @key_id. - * - * Returns: (transfer none) (nullable): the data element, or %NULL if - * it is not found. - */ - - -/** - * g_datalist_id_remove_data: - * @dl: a datalist. - * @q: the #GQuark identifying the data element. - * - * Removes an element, using its #GQuark identifier. - */ - - -/** - * g_datalist_id_remove_no_notify: (skip) - * @datalist: a datalist. - * @key_id: the #GQuark identifying a data element. - * - * Removes an element, without calling its destroy notification - * function. - * - * Returns: (nullable): the data previously stored at @key_id, - * or %NULL if none. - */ - - -/** - * g_datalist_id_replace_data: (skip) - * @datalist: location of a datalist - * @key_id: the #GQuark identifying a data element - * @oldval: (nullable): the old value to compare against - * @newval: (nullable): the new value to replace it with - * @destroy: (nullable): destroy notify for the new value - * @old_destroy: (out) (optional): destroy notify for the existing value - * - * Compares the member that is associated with @key_id in - * @datalist to @oldval, and if they are the same, replace - * @oldval with @newval. - * - * This is like a typical atomic compare-and-exchange - * operation, for a member of @datalist. - * - * If the previous value was replaced then ownership of the - * old value (@oldval) is passed to the caller, including - * the registered destroy notify for it (passed out in @old_destroy). - * Its up to the caller to free this as he wishes, which may - * or may not include using @old_destroy as sometimes replacement - * should not destroy the object in the normal way. - * - * Returns: %TRUE if the existing value for @key_id was replaced - * by @newval, %FALSE otherwise. - * Since: 2.34 - */ - - -/** - * g_datalist_id_set_data: - * @dl: a datalist. - * @q: the #GQuark to identify the data element. - * @d: (nullable): the data element, or %NULL to remove any previous element - * corresponding to @q. - * - * Sets the data corresponding to the given #GQuark id. Any previous - * data with the same key is removed, and its destroy function is - * called. - */ - - -/** - * g_datalist_id_set_data_full: (skip) - * @datalist: a datalist. - * @key_id: the #GQuark to identify the data element. - * @data: (nullable): the data element or %NULL to remove any previous element - * corresponding to @key_id. - * @destroy_func: (nullable): the function to call when the data element is - * removed. This function will be called with the data - * element and can be used to free any memory allocated - * for it. If @data is %NULL, then @destroy_func must - * also be %NULL. - * - * Sets the data corresponding to the given #GQuark id, and the - * function to be called when the element is removed from the datalist. - * Any previous data with the same key is removed, and its destroy - * function is called. - */ - - -/** - * g_datalist_init: (skip) - * @datalist: a pointer to a pointer to a datalist. - * - * Resets the datalist to %NULL. It does not free any memory or call - * any destroy functions. - */ - - -/** - * g_datalist_remove_data: - * @dl: a datalist. - * @k: the string identifying the data element. - * - * Removes an element using its string identifier. The data element's - * destroy function is called if it has been set. - */ - - -/** - * g_datalist_remove_no_notify: (skip) - * @dl: a datalist. - * @k: the string identifying the data element. - * - * Removes an element, without calling its destroy notifier. - */ - - -/** - * g_datalist_set_data: - * @dl: a datalist. - * @k: the string to identify the data element. - * @d: (nullable): the data element, or %NULL to remove any previous element - * corresponding to @k. - * - * Sets the data element corresponding to the given string identifier. - */ - - -/** - * g_datalist_set_data_full: (skip) - * @dl: a datalist. - * @k: the string to identify the data element. - * @d: (nullable): the data element, or %NULL to remove any previous element - * corresponding to @k. - * @f: (nullable): the function to call when the data element is removed. - * This function will be called with the data element and can be used to - * free any memory allocated for it. If @d is %NULL, then @f must - * also be %NULL. - * - * Sets the data element corresponding to the given string identifier, - * and the function to be called when the data element is removed. - */ - - -/** - * g_datalist_set_flags: - * @datalist: pointer to the location that holds a list - * @flags: the flags to turn on. The values of the flags are - * restricted by %G_DATALIST_FLAGS_MASK (currently - * 3; giving two possible boolean flags). - * A value for @flags that doesn't fit within the mask is - * an error. - * - * Turns on flag values for a data list. This function is used - * to keep a small number of boolean flags in an object with - * a data list without using any additional space. It is - * not generally useful except in circumstances where space - * is very tight. (It is used in the base #GObject type, for - * example.) - * - * Since: 2.8 - */ - - -/** - * g_datalist_unset_flags: - * @datalist: pointer to the location that holds a list - * @flags: the flags to turn off. The values of the flags are - * restricted by %G_DATALIST_FLAGS_MASK (currently - * 3: giving two possible boolean flags). - * A value for @flags that doesn't fit within the mask is - * an error. - * - * Turns off flag values for a data list. See g_datalist_unset_flags() - * - * Since: 2.8 - */ - - -/** - * g_dataset_destroy: - * @dataset_location: (not nullable): the location identifying the dataset. - * - * Destroys the dataset, freeing all memory allocated, and calling any - * destroy functions set for data elements. - */ - - -/** - * g_dataset_foreach: - * @dataset_location: (not nullable): the location identifying the dataset. - * @func: (scope call): the function to call for each data element. - * @user_data: (closure): user data to pass to the function. - * - * Calls the given function for each data element which is associated - * with the given location. Note that this function is NOT thread-safe. - * So unless @dataset_location can be protected from any modifications - * during invocation of this function, it should not be called. - * - * @func can make changes to the dataset, but the iteration will not - * reflect changes made during the g_dataset_foreach() call, other - * than skipping over elements that are removed. - */ - - -/** - * g_dataset_get_data: - * @l: the location identifying the dataset. - * @k: the string identifying the data element. - * - * Gets the data element corresponding to a string. - * - * Returns: (transfer none) (nullable): the data element corresponding to - * the string, or %NULL if it is not found. - */ - - -/** - * g_dataset_id_get_data: - * @dataset_location: (not nullable): the location identifying the dataset. - * @key_id: the #GQuark id to identify the data element. - * - * Gets the data element corresponding to a #GQuark. - * - * Returns: (transfer none) (nullable): the data element corresponding to - * the #GQuark, or %NULL if it is not found. - */ - - -/** - * g_dataset_id_remove_data: - * @l: the location identifying the dataset. - * @k: the #GQuark id identifying the data element. - * - * Removes a data element from a dataset. The data element's destroy - * function is called if it has been set. - */ - - -/** - * g_dataset_id_remove_no_notify: (skip) - * @dataset_location: (not nullable): the location identifying the dataset. - * @key_id: the #GQuark ID identifying the data element. - * - * Removes an element, without calling its destroy notification - * function. - * - * Returns: (nullable): the data previously stored at @key_id, - * or %NULL if none. - */ - - -/** - * g_dataset_id_set_data: - * @l: the location identifying the dataset. - * @k: the #GQuark id to identify the data element. - * @d: the data element. - * - * Sets the data element associated with the given #GQuark id. Any - * previous data with the same key is removed, and its destroy function - * is called. - */ - - -/** - * g_dataset_id_set_data_full: (skip) - * @dataset_location: (not nullable): the location identifying the dataset. - * @key_id: the #GQuark id to identify the data element. - * @data: the data element. - * @destroy_func: the function to call when the data element is - * removed. This function will be called with the data - * element and can be used to free any memory allocated - * for it. - * - * Sets the data element associated with the given #GQuark id, and also - * the function to call when the data element is destroyed. Any - * previous data with the same key is removed, and its destroy function - * is called. - */ - - -/** - * g_dataset_remove_data: - * @l: the location identifying the dataset. - * @k: the string identifying the data element. - * - * Removes a data element corresponding to a string. Its destroy - * function is called if it has been set. - */ - - -/** - * g_dataset_remove_no_notify: (skip) - * @l: the location identifying the dataset. - * @k: the string identifying the data element. - * - * Removes an element, without calling its destroy notifier. - */ - - -/** - * g_dataset_set_data: - * @l: the location identifying the dataset. - * @k: the string to identify the data element. - * @d: the data element. - * - * Sets the data corresponding to the given string identifier. - */ - - -/** - * g_dataset_set_data_full: (skip) - * @l: the location identifying the dataset. - * @k: the string to identify the data element. - * @d: the data element. - * @f: the function to call when the data element is removed. This - * function will be called with the data element and can be used to - * free any memory allocated for it. - * - * Sets the data corresponding to the given string identifier, and the - * function to call when the data element is destroyed. - */ - - -/** - * g_date_add_days: - * @date: a #GDate to increment - * @n_days: number of days to move the date forward - * - * Increments a date some number of days. - * To move forward by weeks, add weeks*7 days. - * The date must be valid. - */ - - -/** - * g_date_add_months: - * @date: a #GDate to increment - * @n_months: number of months to move forward - * - * Increments a date by some number of months. - * If the day of the month is greater than 28, - * this routine may change the day of the month - * (because the destination month may not have - * the current day in it). The date must be valid. - */ - - -/** - * g_date_add_years: - * @date: a #GDate to increment - * @n_years: number of years to move forward - * - * Increments a date by some number of years. - * If the date is February 29, and the destination - * year is not a leap year, the date will be changed - * to February 28. The date must be valid. - */ - - -/** - * g_date_clamp: - * @date: a #GDate to clamp - * @min_date: minimum accepted value for @date - * @max_date: maximum accepted value for @date - * - * If @date is prior to @min_date, sets @date equal to @min_date. - * If @date falls after @max_date, sets @date equal to @max_date. - * Otherwise, @date is unchanged. - * Either of @min_date and @max_date may be %NULL. - * All non-%NULL dates must be valid. - */ - - -/** - * g_date_clear: - * @date: pointer to one or more dates to clear - * @n_dates: number of dates to clear - * - * Initializes one or more #GDate structs to a safe but invalid - * state. The cleared dates will not represent an existing date, but will - * not contain garbage. Useful to init a date declared on the stack. - * Validity can be tested with g_date_valid(). - */ - - -/** - * g_date_compare: - * @lhs: first date to compare - * @rhs: second date to compare - * - * qsort()-style comparison function for dates. - * Both dates must be valid. - * - * Returns: 0 for equal, less than zero if @lhs is less than @rhs, - * greater than zero if @lhs is greater than @rhs - */ - - -/** - * g_date_copy: - * @date: a #GDate to copy - * - * Copies a GDate to a newly-allocated GDate. If the input was invalid - * (as determined by g_date_valid()), the invalid state will be copied - * as is into the new object. - * - * Returns: (transfer full): a newly-allocated #GDate initialized from @date - * Since: 2.56 - */ - - -/** - * g_date_days_between: - * @date1: the first date - * @date2: the second date - * - * Computes the number of days between two dates. - * If @date2 is prior to @date1, the returned value is negative. - * Both dates must be valid. - * - * Returns: the number of days between @date1 and @date2 - */ - - -/** - * g_date_free: - * @date: a #GDate to free - * - * Frees a #GDate returned from g_date_new(). - */ - - -/** - * g_date_get_day: - * @date: a #GDate to extract the day of the month from - * - * Returns the day of the month. The date must be valid. - * - * Returns: day of the month - */ - - -/** - * g_date_get_day_of_year: - * @date: a #GDate to extract day of year from - * - * Returns the day of the year, where Jan 1 is the first day of the - * year. The date must be valid. - * - * Returns: day of the year - */ - - -/** - * g_date_get_days_in_month: - * @month: month - * @year: year - * - * Returns the number of days in a month, taking leap - * years into account. - * - * Returns: number of days in @month during the @year - */ - - -/** - * g_date_get_iso8601_week_of_year: - * @date: a valid #GDate - * - * Returns the week of the year, where weeks are interpreted according - * to ISO 8601. - * - * Returns: ISO 8601 week number of the year. - * Since: 2.6 - */ - - -/** - * g_date_get_julian: - * @date: a #GDate to extract the Julian day from - * - * Returns the Julian day or "serial number" of the #GDate. The - * Julian day is simply the number of days since January 1, Year 1; i.e., - * January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2, - * etc. The date must be valid. - * - * Returns: Julian day - */ - - -/** - * g_date_get_monday_week_of_year: - * @date: a #GDate - * - * Returns the week of the year, where weeks are understood to start on - * Monday. If the date is before the first Monday of the year, return 0. - * The date must be valid. - * - * Returns: week of the year - */ - - -/** - * g_date_get_monday_weeks_in_year: - * @year: a year - * - * Returns the number of weeks in the year, where weeks - * are taken to start on Monday. Will be 52 or 53. The - * date must be valid. (Years always have 52 7-day periods, - * plus 1 or 2 extra days depending on whether it's a leap - * year. This function is basically telling you how many - * Mondays are in the year, i.e. there are 53 Mondays if - * one of the extra days happens to be a Monday.) - * - * Returns: number of Mondays in the year - */ - - -/** - * g_date_get_month: - * @date: a #GDate to get the month from - * - * Returns the month of the year. The date must be valid. - * - * Returns: month of the year as a #GDateMonth - */ - - -/** - * g_date_get_sunday_week_of_year: - * @date: a #GDate - * - * Returns the week of the year during which this date falls, if - * weeks are understood to begin on Sunday. The date must be valid. - * Can return 0 if the day is before the first Sunday of the year. - * - * Returns: week number - */ - - -/** - * g_date_get_sunday_weeks_in_year: - * @year: year to count weeks in - * - * Returns the number of weeks in the year, where weeks - * are taken to start on Sunday. Will be 52 or 53. The - * date must be valid. (Years always have 52 7-day periods, - * plus 1 or 2 extra days depending on whether it's a leap - * year. This function is basically telling you how many - * Sundays are in the year, i.e. there are 53 Sundays if - * one of the extra days happens to be a Sunday.) - * - * Returns: the number of weeks in @year - */ - - -/** - * g_date_get_weekday: - * @date: a #GDate - * - * Returns the day of the week for a #GDate. The date must be valid. - * - * Returns: day of the week as a #GDateWeekday. - */ - - -/** - * g_date_get_year: - * @date: a #GDate - * - * Returns the year of a #GDate. The date must be valid. - * - * Returns: year in which the date falls - */ - - -/** - * g_date_is_first_of_month: - * @date: a #GDate to check - * - * Returns %TRUE if the date is on the first of a month. - * The date must be valid. - * - * Returns: %TRUE if the date is the first of the month - */ - - -/** - * g_date_is_last_of_month: - * @date: a #GDate to check - * - * Returns %TRUE if the date is the last day of the month. - * The date must be valid. - * - * Returns: %TRUE if the date is the last day of the month - */ - - -/** - * g_date_is_leap_year: - * @year: year to check - * - * Returns %TRUE if the year is a leap year. - * - * For the purposes of this function, leap year is every year - * divisible by 4 unless that year is divisible by 100. If it - * is divisible by 100 it would be a leap year only if that year - * is also divisible by 400. - * - * Returns: %TRUE if the year is a leap year - */ - - -/** - * g_date_new: - * - * Allocates a #GDate and initializes - * it to a safe state. The new date will - * be cleared (as if you'd called g_date_clear()) but invalid (it won't - * represent an existing day). Free the return value with g_date_free(). - * - * Returns: a newly-allocated #GDate - */ - - -/** - * g_date_new_dmy: - * @day: day of the month - * @month: month of the year - * @year: year - * - * Like g_date_new(), but also sets the value of the date. Assuming the - * day-month-year triplet you pass in represents an existing day, the - * returned date will be valid. - * - * Returns: a newly-allocated #GDate initialized with @day, @month, and @year - */ - - -/** - * g_date_new_julian: - * @julian_day: days since January 1, Year 1 - * - * Like g_date_new(), but also sets the value of the date. Assuming the - * Julian day number you pass in is valid (greater than 0, less than an - * unreasonably large number), the returned date will be valid. - * - * Returns: a newly-allocated #GDate initialized with @julian_day - */ - - -/** - * g_date_order: - * @date1: the first date - * @date2: the second date - * - * Checks if @date1 is less than or equal to @date2, - * and swap the values if this is not the case. - */ - - -/** - * g_date_set_day: - * @date: a #GDate - * @day: day to set - * - * Sets the day of the month for a #GDate. If the resulting - * day-month-year triplet is invalid, the date will be invalid. - */ - - -/** - * g_date_set_dmy: - * @date: a #GDate - * @day: day - * @month: month - * @y: year - * - * Sets the value of a #GDate from a day, month, and year. - * The day-month-year triplet must be valid; if you aren't - * sure it is, call g_date_valid_dmy() to check before you - * set it. - */ - - -/** - * g_date_set_julian: - * @date: a #GDate - * @julian_date: Julian day number (days since January 1, Year 1) - * - * Sets the value of a #GDate from a Julian day number. - */ - - -/** - * g_date_set_month: - * @date: a #GDate - * @month: month to set - * - * Sets the month of the year for a #GDate. If the resulting - * day-month-year triplet is invalid, the date will be invalid. - */ - - -/** - * g_date_set_parse: - * @date: a #GDate to fill in - * @str: string to parse - * - * Parses a user-inputted string @str, and try to figure out what date it - * represents, taking the [current locale][setlocale] into account. If the - * string is successfully parsed, the date will be valid after the call. - * Otherwise, it will be invalid. You should check using g_date_valid() - * to see whether the parsing succeeded. - * - * This function is not appropriate for file formats and the like; it - * isn't very precise, and its exact behavior varies with the locale. - * It's intended to be a heuristic routine that guesses what the user - * means by a given string (and it does work pretty well in that - * capacity). - */ - - -/** - * g_date_set_time: - * @date: a #GDate. - * @time_: #GTime value to set. - * - * Sets the value of a date from a #GTime value. - * The time to date conversion is done using the user's current timezone. - * - * Deprecated: 2.10: Use g_date_set_time_t() instead. - */ - - -/** - * g_date_set_time_t: - * @date: a #GDate - * @timet: time_t value to set - * - * Sets the value of a date to the date corresponding to a time - * specified as a time_t. The time to date conversion is done using - * the user's current timezone. - * - * To set the value of a date to the current day, you could write: - * |[ - * time_t now = time (NULL); - * if (now == (time_t) -1) - * // handle the error - * g_date_set_time_t (date, now); - * ]| - * - * Since: 2.10 - */ - - -/** - * g_date_set_time_val: - * @date: a #GDate - * @timeval: #GTimeVal value to set - * - * Sets the value of a date from a #GTimeVal value. Note that the - * @tv_usec member is ignored, because #GDate can't make use of the - * additional precision. - * - * The time to date conversion is done using the user's current timezone. - * - * Since: 2.10 - * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use g_date_set_time_t() - * instead. - */ - - -/** - * g_date_set_year: - * @date: a #GDate - * @year: year to set - * - * Sets the year for a #GDate. If the resulting day-month-year - * triplet is invalid, the date will be invalid. - */ - - -/** - * g_date_strftime: - * @s: destination buffer - * @slen: buffer size - * @format: format string - * @date: valid #GDate - * - * Generates a printed representation of the date, in a - * [locale][setlocale]-specific way. - * Works just like the platform's C library strftime() function, - * but only accepts date-related formats; time-related formats - * give undefined results. Date must be valid. Unlike strftime() - * (which uses the locale encoding), works on a UTF-8 format - * string and stores a UTF-8 result. - * - * This function does not provide any conversion specifiers in - * addition to those implemented by the platform's C library. - * For example, don't expect that using g_date_strftime() would - * make the \%F provided by the C99 strftime() work on Windows - * where the C library only complies to C89. - * - * Returns: number of characters written to the buffer, or 0 the buffer was too small - */ - - -/** - * g_date_subtract_days: - * @date: a #GDate to decrement - * @n_days: number of days to move - * - * Moves a date some number of days into the past. - * To move by weeks, just move by weeks*7 days. - * The date must be valid. - */ - - -/** - * g_date_subtract_months: - * @date: a #GDate to decrement - * @n_months: number of months to move - * - * Moves a date some number of months into the past. - * If the current day of the month doesn't exist in - * the destination month, the day of the month - * may change. The date must be valid. - */ - - -/** - * g_date_subtract_years: - * @date: a #GDate to decrement - * @n_years: number of years to move - * - * Moves a date some number of years into the past. - * If the current day doesn't exist in the destination - * year (i.e. it's February 29 and you move to a non-leap-year) - * then the day is changed to February 29. The date - * must be valid. - */ - - -/** - * g_date_time_add: - * @datetime: a #GDateTime - * @timespan: a #GTimeSpan - * - * Creates a copy of @datetime and adds the specified timespan to the copy. - * - * Returns: (transfer full) (nullable): the newly created #GDateTime which - * should be freed with g_date_time_unref(), or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_add_days: - * @datetime: a #GDateTime - * @days: the number of days - * - * Creates a copy of @datetime and adds the specified number of days to the - * copy. Add negative values to subtract days. - * - * Returns: (transfer full) (nullable): the newly created #GDateTime which - * should be freed with g_date_time_unref(), or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_add_full: - * @datetime: a #GDateTime - * @years: the number of years to add - * @months: the number of months to add - * @days: the number of days to add - * @hours: the number of hours to add - * @minutes: the number of minutes to add - * @seconds: the number of seconds to add - * - * Creates a new #GDateTime adding the specified values to the current date and - * time in @datetime. Add negative values to subtract. - * - * Returns: (transfer full) (nullable): the newly created #GDateTime which - * should be freed with g_date_time_unref(), or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_add_hours: - * @datetime: a #GDateTime - * @hours: the number of hours to add - * - * Creates a copy of @datetime and adds the specified number of hours. - * Add negative values to subtract hours. - * - * Returns: (transfer full) (nullable): the newly created #GDateTime which - * should be freed with g_date_time_unref(), or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_add_minutes: - * @datetime: a #GDateTime - * @minutes: the number of minutes to add - * - * Creates a copy of @datetime adding the specified number of minutes. - * Add negative values to subtract minutes. - * - * Returns: (transfer full) (nullable): the newly created #GDateTime which - * should be freed with g_date_time_unref(), or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_add_months: - * @datetime: a #GDateTime - * @months: the number of months - * - * Creates a copy of @datetime and adds the specified number of months to the - * copy. Add negative values to subtract months. - * - * The day of the month of the resulting #GDateTime is clamped to the number - * of days in the updated calendar month. For example, if adding 1 month to - * 31st January 2018, the result would be 28th February 2018. In 2020 (a leap - * year), the result would be 29th February. - * - * Returns: (transfer full) (nullable): the newly created #GDateTime which - * should be freed with g_date_time_unref(), or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_add_seconds: - * @datetime: a #GDateTime - * @seconds: the number of seconds to add - * - * Creates a copy of @datetime and adds the specified number of seconds. - * Add negative values to subtract seconds. - * - * Returns: (transfer full) (nullable): the newly created #GDateTime which - * should be freed with g_date_time_unref(), or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_add_weeks: - * @datetime: a #GDateTime - * @weeks: the number of weeks - * - * Creates a copy of @datetime and adds the specified number of weeks to the - * copy. Add negative values to subtract weeks. - * - * Returns: (transfer full) (nullable): the newly created #GDateTime which - * should be freed with g_date_time_unref(), or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_add_years: - * @datetime: a #GDateTime - * @years: the number of years - * - * Creates a copy of @datetime and adds the specified number of years to the - * copy. Add negative values to subtract years. - * - * As with g_date_time_add_months(), if the resulting date would be 29th - * February on a non-leap year, the day will be clamped to 28th February. - * - * Returns: (transfer full) (nullable): the newly created #GDateTime which - * should be freed with g_date_time_unref(), or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_compare: - * @dt1: (type GDateTime) (not nullable): first #GDateTime to compare - * @dt2: (type GDateTime) (not nullable): second #GDateTime to compare - * - * A comparison function for #GDateTimes that is suitable - * as a #GCompareFunc. Both #GDateTimes must be non-%NULL. - * - * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater - * than @dt2. - * Since: 2.26 - */ - - -/** - * g_date_time_difference: - * @end: a #GDateTime - * @begin: a #GDateTime - * - * Calculates the difference in time between @end and @begin. The - * #GTimeSpan that is returned is effectively @end - @begin (ie: - * positive if the first parameter is larger). - * - * Returns: the difference between the two #GDateTime, as a time - * span expressed in microseconds. - * Since: 2.26 - */ - - -/** - * g_date_time_equal: - * @dt1: (type GDateTime) (not nullable): a #GDateTime - * @dt2: (type GDateTime) (not nullable): a #GDateTime - * - * Checks to see if @dt1 and @dt2 are equal. - * - * Equal here means that they represent the same moment after converting - * them to the same time zone. - * - * Returns: %TRUE if @dt1 and @dt2 are equal - * Since: 2.26 - */ - - -/** - * g_date_time_format: - * @datetime: A #GDateTime - * @format: a valid UTF-8 string, containing the format for the - * #GDateTime - * - * Creates a newly allocated string representing the requested @format. - * - * The format strings understood by this function are a subset of the - * strftime() format language as specified by C99. The \%D, \%U and \%W - * conversions are not supported, nor is the 'E' modifier. The GNU - * extensions \%k, \%l, \%s and \%P are supported, however, as are the - * '0', '_' and '-' modifiers. The Python extension \%f is also supported. - * - * In contrast to strftime(), this function always produces a UTF-8 - * string, regardless of the current locale. Note that the rendering of - * many formats is locale-dependent and may not match the strftime() - * output exactly. - * - * The following format specifiers are supported: - * - * - \%a: the abbreviated weekday name according to the current locale - * - \%A: the full weekday name according to the current locale - * - \%b: the abbreviated month name according to the current locale - * - \%B: the full month name according to the current locale - * - \%c: the preferred date and time representation for the current locale - * - \%C: the century number (year/100) as a 2-digit integer (00-99) - * - \%d: the day of the month as a decimal number (range 01 to 31) - * - \%e: the day of the month as a decimal number (range 1 to 31) - * - \%F: equivalent to `%Y-%m-%d` (the ISO 8601 date format) - * - \%g: the last two digits of the ISO 8601 week-based year as a - * decimal number (00-99). This works well with \%V and \%u. - * - \%G: the ISO 8601 week-based year as a decimal number. This works - * well with \%V and \%u. - * - \%h: equivalent to \%b - * - \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23) - * - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12) - * - \%j: the day of the year as a decimal number (range 001 to 366) - * - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23); - * single digits are preceded by a blank - * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12); - * single digits are preceded by a blank - * - \%m: the month as a decimal number (range 01 to 12) - * - \%M: the minute as a decimal number (range 00 to 59) - * - \%f: the microsecond as a decimal number (range 000000 to 999999) - * - \%p: either "AM" or "PM" according to the given time value, or the - * corresponding strings for the current locale. Noon is treated as - * "PM" and midnight as "AM". Use of this format specifier is discouraged, as - * many locales have no concept of AM/PM formatting. Use \%c or \%X instead. - * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for - * the current locale. Use of this format specifier is discouraged, as - * many locales have no concept of AM/PM formatting. Use \%c or \%X instead. - * - \%r: the time in a.m. or p.m. notation. Use of this format specifier is - * discouraged, as many locales have no concept of AM/PM formatting. Use \%c - * or \%X instead. - * - \%R: the time in 24-hour notation (\%H:\%M) - * - \%s: the number of seconds since the Epoch, that is, since 1970-01-01 - * 00:00:00 UTC - * - \%S: the second as a decimal number (range 00 to 60) - * - \%t: a tab character - * - \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S) - * - \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7, - * Monday being 1. This works well with \%G and \%V. - * - \%V: the ISO 8601 standard week number of the current year as a decimal - * number, range 01 to 53, where week 1 is the first week that has at - * least 4 days in the new year. See g_date_time_get_week_of_year(). - * This works well with \%G and \%u. - * - \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0. - * This is not the ISO 8601 standard format -- use \%u instead. - * - \%x: the preferred date representation for the current locale without - * the time - * - \%X: the preferred time representation for the current locale without - * the date - * - \%y: the year as a decimal number without the century - * - \%Y: the year as a decimal number including the century - * - \%z: the time zone as an offset from UTC (+hhmm) - * - \%:z: the time zone as an offset from UTC (+hh:mm). - * This is a gnulib strftime() extension. Since: 2.38 - * - \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a - * gnulib strftime() extension. Since: 2.38 - * - \%:::z: the time zone as an offset from UTC, with : to necessary - * precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38 - * - \%Z: the time zone or name or abbreviation - * - \%\%: a literal \% character - * - * Some conversion specifications can be modified by preceding the - * conversion specifier by one or more modifier characters. The - * following modifiers are supported for many of the numeric - * conversions: - * - * - O: Use alternative numeric symbols, if the current locale supports those. - * - _: Pad a numeric result with spaces. This overrides the default padding - * for the specifier. - * - -: Do not pad a numeric result. This overrides the default padding - * for the specifier. - * - 0: Pad a numeric result with zeros. This overrides the default padding - * for the specifier. - * - * Additionally, when O is used with B, b, or h, it produces the alternative - * form of a month name. The alternative form should be used when the month - * name is used without a day number (e.g., standalone). It is required in - * some languages (Baltic, Slavic, Greek, and more) due to their grammatical - * rules. For other languages there is no difference. \%OB is a GNU and BSD - * strftime() extension expected to be added to the future POSIX specification, - * \%Ob and \%Oh are GNU strftime() extensions. Since: 2.56 - * - * Returns: (transfer full) (nullable): a newly allocated string formatted to - * the requested format or %NULL in the case that there was an error (such - * as a format specifier not being supported in the current locale). The - * string should be freed with g_free(). - * Since: 2.26 - */ - - -/** - * g_date_time_format_iso8601: - * @datetime: A #GDateTime - * - * Format @datetime in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), - * including the date, time and time zone, and return that as a UTF-8 encoded - * string. - * - * Since GLib 2.66, this will output to sub-second precision if needed. - * - * Returns: (transfer full) (nullable): a newly allocated string formatted in - * ISO 8601 format or %NULL in the case that there was an error. The string - * should be freed with g_free(). - * Since: 2.62 - */ - - -/** - * g_date_time_get_day_of_month: - * @datetime: a #GDateTime - * - * Retrieves the day of the month represented by @datetime in the gregorian - * calendar. - * - * Returns: the day of the month - * Since: 2.26 - */ - - -/** - * g_date_time_get_day_of_week: - * @datetime: a #GDateTime - * - * Retrieves the ISO 8601 day of the week on which @datetime falls (1 is - * Monday, 2 is Tuesday... 7 is Sunday). - * - * Returns: the day of the week - * Since: 2.26 - */ - - -/** - * g_date_time_get_day_of_year: - * @datetime: a #GDateTime - * - * Retrieves the day of the year represented by @datetime in the Gregorian - * calendar. - * - * Returns: the day of the year - * Since: 2.26 - */ - - -/** - * g_date_time_get_hour: - * @datetime: a #GDateTime - * - * Retrieves the hour of the day represented by @datetime - * - * Returns: the hour of the day - * Since: 2.26 - */ - - -/** - * g_date_time_get_microsecond: - * @datetime: a #GDateTime - * - * Retrieves the microsecond of the date represented by @datetime - * - * Returns: the microsecond of the second - * Since: 2.26 - */ - - -/** - * g_date_time_get_minute: - * @datetime: a #GDateTime - * - * Retrieves the minute of the hour represented by @datetime - * - * Returns: the minute of the hour - * Since: 2.26 - */ - - -/** - * g_date_time_get_month: - * @datetime: a #GDateTime - * - * Retrieves the month of the year represented by @datetime in the Gregorian - * calendar. - * - * Returns: the month represented by @datetime - * Since: 2.26 - */ - - -/** - * g_date_time_get_second: - * @datetime: a #GDateTime - * - * Retrieves the second of the minute represented by @datetime - * - * Returns: the second represented by @datetime - * Since: 2.26 - */ - - -/** - * g_date_time_get_seconds: - * @datetime: a #GDateTime - * - * Retrieves the number of seconds since the start of the last minute, - * including the fractional part. - * - * Returns: the number of seconds - * Since: 2.26 - */ - - -/** - * g_date_time_get_timezone: - * @datetime: a #GDateTime - * - * Get the time zone for this @datetime. - * - * Returns: (transfer none): the time zone - * Since: 2.58 - */ - - -/** - * g_date_time_get_timezone_abbreviation: - * @datetime: a #GDateTime - * - * Determines the time zone abbreviation to be used at the time and in - * the time zone of @datetime. - * - * For example, in Toronto this is currently "EST" during the winter - * months and "EDT" during the summer months when daylight savings - * time is in effect. - * - * Returns: (transfer none): the time zone abbreviation. The returned - * string is owned by the #GDateTime and it should not be - * modified or freed - * Since: 2.26 - */ - - -/** - * g_date_time_get_utc_offset: - * @datetime: a #GDateTime - * - * Determines the offset to UTC in effect at the time and in the time - * zone of @datetime. - * - * The offset is the number of microseconds that you add to UTC time to - * arrive at local time for the time zone (ie: negative numbers for time - * zones west of GMT, positive numbers for east). - * - * If @datetime represents UTC time, then the offset is always zero. - * - * Returns: the number of microseconds that should be added to UTC to - * get the local time - * Since: 2.26 - */ - - -/** - * g_date_time_get_week_numbering_year: - * @datetime: a #GDateTime - * - * Returns the ISO 8601 week-numbering year in which the week containing - * @datetime falls. - * - * This function, taken together with g_date_time_get_week_of_year() and - * g_date_time_get_day_of_week() can be used to determine the full ISO - * week date on which @datetime falls. - * - * This is usually equal to the normal Gregorian year (as returned by - * g_date_time_get_year()), except as detailed below: - * - * For Thursday, the week-numbering year is always equal to the usual - * calendar year. For other days, the number is such that every day - * within a complete week (Monday to Sunday) is contained within the - * same week-numbering year. - * - * For Monday, Tuesday and Wednesday occurring near the end of the year, - * this may mean that the week-numbering year is one greater than the - * calendar year (so that these days have the same week-numbering year - * as the Thursday occurring early in the next year). - * - * For Friday, Saturday and Sunday occurring near the start of the year, - * this may mean that the week-numbering year is one less than the - * calendar year (so that these days have the same week-numbering year - * as the Thursday occurring late in the previous year). - * - * An equivalent description is that the week-numbering year is equal to - * the calendar year containing the majority of the days in the current - * week (Monday to Sunday). - * - * Note that January 1 0001 in the proleptic Gregorian calendar is a - * Monday, so this function never returns 0. - * - * Returns: the ISO 8601 week-numbering year for @datetime - * Since: 2.26 - */ - - -/** - * g_date_time_get_week_of_year: - * @datetime: a #GDateTime - * - * Returns the ISO 8601 week number for the week containing @datetime. - * The ISO 8601 week number is the same for every day of the week (from - * Moday through Sunday). That can produce some unusual results - * (described below). - * - * The first week of the year is week 1. This is the week that contains - * the first Thursday of the year. Equivalently, this is the first week - * that has more than 4 of its days falling within the calendar year. - * - * The value 0 is never returned by this function. Days contained - * within a year but occurring before the first ISO 8601 week of that - * year are considered as being contained in the last week of the - * previous year. Similarly, the final days of a calendar year may be - * considered as being part of the first ISO 8601 week of the next year - * if 4 or more days of that week are contained within the new year. - * - * Returns: the ISO 8601 week number for @datetime. - * Since: 2.26 - */ - - -/** - * g_date_time_get_year: - * @datetime: A #GDateTime - * - * Retrieves the year represented by @datetime in the Gregorian calendar. - * - * Returns: the year represented by @datetime - * Since: 2.26 - */ - - -/** - * g_date_time_get_ymd: - * @datetime: a #GDateTime. - * @year: (out) (optional): the return location for the gregorian year, or %NULL. - * @month: (out) (optional): the return location for the month of the year, or %NULL. - * @day: (out) (optional): the return location for the day of the month, or %NULL. - * - * Retrieves the Gregorian day, month, and year of a given #GDateTime. - * - * Since: 2.26 - */ - - -/** - * g_date_time_hash: - * @datetime: (type GDateTime) (not nullable): a #GDateTime - * - * Hashes @datetime into a #guint, suitable for use within #GHashTable. - * - * Returns: a #guint containing the hash - * Since: 2.26 - */ - - -/** - * g_date_time_is_daylight_savings: - * @datetime: a #GDateTime - * - * Determines if daylight savings time is in effect at the time and in - * the time zone of @datetime. - * - * Returns: %TRUE if daylight savings time is in effect - * Since: 2.26 - */ - - -/** - * g_date_time_new: (constructor) - * @tz: a #GTimeZone - * @year: the year component of the date - * @month: the month component of the date - * @day: the day component of the date - * @hour: the hour component of the date - * @minute: the minute component of the date - * @seconds: the number of seconds past the minute - * - * Creates a new #GDateTime corresponding to the given date and time in - * the time zone @tz. - * - * The @year must be between 1 and 9999, @month between 1 and 12 and @day - * between 1 and 28, 29, 30 or 31 depending on the month and the year. - * - * @hour must be between 0 and 23 and @minute must be between 0 and 59. - * - * @seconds must be at least 0.0 and must be strictly less than 60.0. - * It will be rounded down to the nearest microsecond. - * - * If the given time is not representable in the given time zone (for - * example, 02:30 on March 14th 2010 in Toronto, due to daylight savings - * time) then the time will be rounded up to the nearest existing time - * (in this case, 03:00). If this matters to you then you should verify - * the return value for containing the same as the numbers you gave. - * - * In the case that the given time is ambiguous in the given time zone - * (for example, 01:30 on November 7th 2010 in Toronto, due to daylight - * savings time) then the time falling within standard (ie: - * non-daylight) time is taken. - * - * It not considered a programmer error for the values to this function - * to be out of range, but in the case that they are, the function will - * return %NULL. - * - * You should release the return value by calling g_date_time_unref() - * when you are done with it. - * - * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_new_from_iso8601: (constructor) - * @text: an ISO 8601 formatted time string. - * @default_tz: (nullable): a #GTimeZone to use if the text doesn't contain a - * timezone, or %NULL. - * - * Creates a #GDateTime corresponding to the given - * [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601) - * @text. ISO 8601 strings of the form