diff options
| -rw-r--r-- | .gitlab-ci.yml | 5 | ||||
| -rw-r--r-- | .gitlab-ci/test-msys2-meson.sh | 1 | ||||
| -rw-r--r-- | gir/gio-2.0.c | 43896 | ||||
| -rw-r--r-- | gir/glib-2.0.c | 42618 | ||||
| -rw-r--r-- | gir/gmodule-2.0.c | 289 | ||||
| -rw-r--r-- | gir/gobject-2.0.c | 7336 | ||||
| -rw-r--r-- | gir/meson.build | 97 | ||||
| -rw-r--r-- | meson.build | 2 | ||||
| -rwxr-xr-x | misc/update-glib-annotations.py | 90 |
9 files changed, 53 insertions, 94281 deletions
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: - * |[<!-- language="C" --> - * // 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: - * |[<!-- language="C" --> - * 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 - * |[<!-- language="C" --> - * { - * "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. - * - * |[<!-- language="C" --> - * 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); - * ]| - * - * |[<!-- language="C" --> - * // 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. - * |[<!-- language="C" --> - * 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. - * |[<!-- language="C" --> - * 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. - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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, [<gnetworking.h>][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: - * - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * // 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 `<gio/gdesktopappinfo.h>` 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. - * - * <!-- TODO: Implementation note about using extended attributes on supported - * file systems --> - * - * ## 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 `<gio/gfiledescriptorbased.h>` 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. - * - * |[<!-- language="C" --> - * 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} - * - *  - * - * 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} - * - *  - * - * 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 `<gio/gnetworking.h>` 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: - * |[ - * <?xml version="1.0" encoding="UTF-8"?> - * <gresources> - * <gresource prefix="/org/gtk/Example"> - * <file>data/splashscreen.png</file> - * <file compressed="true">dialog.ui</file> - * <file preprocess="xml-stripblanks">menumarkup.xml</file> - * <file alias="example.css">data/example.css</file> - * </gresource> - * </gresources> - * ]| - * - * 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 <schemalist> or <schema> - * elements and the category that is specified in the `l10n` attribute of - * the <default> element. The string which is translated includes all text in - * the <default> 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 <default> 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 <default> element to disambiguate multiple - * defaults which use the same string. - * - * For example: - * |[ - * <!-- Translators: A list of words which are not allowed to be typed, in - * GVariant serialization syntax. - * See: https://developer.gnome.org/glib/stable/gvariant-text.html --> - * <default l10n='messages' context='Banned words'>['bad', 'words']</default> - * ]| - * - * 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 <schema> 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 <choice>, - * <enum> or <flags> 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: - * |[ - * <schemalist> - * <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test"> - * - * <key name="greeting" type="s"> - * <default l10n="messages">"Hello, earthlings"</default> - * <summary>A greeting</summary> - * <description> - * Greeting of the invading martians - * </description> - * </key> - * - * <key name="box" type="(ii)"> - * <default>(20,30)</default> - * </key> - * - * <key name="empty-string" type="s"> - * <default>""</default> - * <summary>Empty strings have to be provided in GVariant form</summary> - * </key> - * - * </schema> - * </schemalist> - * ]| - * - * An example for ranges, choices and enumerated types: - * |[ - * <schemalist> - * - * <enum id="org.gtk.Test.myenum"> - * <value nick="first" value="1"/> - * <value nick="second" value="2"/> - * </enum> - * - * <flags id="org.gtk.Test.myflags"> - * <value nick="flag1" value="1"/> - * <value nick="flag2" value="2"/> - * <value nick="flag3" value="4"/> - * </flags> - * - * <schema id="org.gtk.Test"> - * - * <key name="key-with-range" type="i"> - * <range min="1" max="100"/> - * <default>10</default> - * </key> - * - * <key name="key-with-choices" type="s"> - * <choices> - * <choice value='Elisabeth'/> - * <choice value='Annabeth'/> - * <choice value='Joe'/> - * </choices> - * <aliases> - * <alias value='Anna' target='Annabeth'/> - * <alias value='Beth' target='Elisabeth'/> - * </aliases> - * <default>'Joe'</default> - * </key> - * - * <key name='enumerated-key' enum='org.gtk.Test.myenum'> - * <default>'first'</default> - * </key> - * - * <key name='flags-key' flags='org.gtk.Test.myflags'> - * <default>["flag1","flag2"]</default> - * </key> - * </schema> - * </schemalist> - * ]| - * - * ## 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 - * <schema> 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 <child> elements in the parent schema, e.g.: - * |[ - * <schema id="org.foo.MyApp" path="/org/foo/MyApp/"> - * <child name="main" schema="org.foo.MyApp.Window"/> - * </schema> - * ]| - * - * ## 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 <summary> and - * <description> elements, and also any <default> 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 <enum> 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: - * - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * { - * 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: - * - * |[<!-- language="C" --> - * 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, [<gnetworking.h>][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. - * - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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 `<gio/gunixconnection.h>` 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 `<gio/gunixfdlist.h>` 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 `<gio/gunixfdmessage.h>` 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 `<gio/gunixinputstream.h>` 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 `<gio/gunixmounts.h>` 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 `<gio/gunixoutputstream.h>` 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 `<gio/gunixsocketaddress.h>` 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 `<gio/gwin32inputstream.h>` 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 `<gio/gwin32outputstream.h>` 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 "<invalid>" - * 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. - * - * |[<!-- language="C" --> - * // 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. - * - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * // 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.: - * |[<!-- language="C" --> - * 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.: - * |[<!-- language="C" --> - * 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. - * - * |[<!-- language="C" --> - * 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 - * <node> 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.: - * |[<!-- language="C" --> - * 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.: - * |[<!-- language="C" --> - * 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. - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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). - * - * |[<!-- language="C" --> - * // 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: - * |[ - * <menu id='edit-menu'> - * <section> - * <item label='Undo'/> - * <item label='Redo'/> - * </section> - * <section> - * <item label='Cut'/> - * <item label='Copy'/> - * <item label='Paste'/> - * </section> - * </menu> - * ]| - * - * 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). - * |[ - * <menu id='edit-menu'> - * <item> - * <link name='section'> - * <item label='Undo'/> - * <item label='Redo'/> - * </link> - * </item> - * <item> - * <link name='section'> - * <item label='Cut'/> - * <item label='Copy'/> - * <item label='Paste'/> - * </link> - * </item> - * </menu> - * ]| - * - * 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 `<protocol>://[user[:password]@]host:port` or - * `direct://`, where <protocol> 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 <child> 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>][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>][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: - * |[<!-- language="C" --> - * 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 - * - * |[<!-- language="C" --> - * 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 - * |[<!-- language="C" --> - * (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(): - * |[<!-- language="C" --> - * // 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(): - * |[<!-- language="C" --> - * // 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. - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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 - *  - * - Pre order: F, B, A, D, C, E, G, I, H - *  - * - Post order: A, C, E, D, B, H, I, G, F - *  - * - Level order: F, B, G, A, D, I, C, E, H - *  - */ - - -/** - * 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: - * - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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 - * - * |[<!-- language="C" --> - * 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 - * - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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. - * - * |[<!-- language="C" -- - * G_DEPRECATED - * int my_mistake (void); - * ]| - * - * Since: 2.32 - */ - - -/** - * G_DEPRECATED_FOR: - * @f: the name of the function that this function was deprecated for - * - * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark - * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it - * is meant to be portable across different compilers and must be placed - * before the function declaration. - * - * |[<!-- language="C" -- - * G_DEPRECATED_FOR(my_replacement) - * int my_mistake (void); - * ]| - * - * Since: 2.32 - */ - - -/** - * G_DIR_SEPARATOR: - * - * The directory separator character. - * This is '/' on UNIX machines and '\' under Windows. - */ - - -/** - * G_DIR_SEPARATOR_S: - * - * The directory separator as a string. - * This is "/" on UNIX machines and "\" under Windows. - */ - - -/** - * G_E: - * - * The base of natural logarithms. - */ - - -/** - * G_END_DECLS: - * - * Used (along with #G_BEGIN_DECLS) to bracket header files. If the - * compiler in use is a C++ compiler, adds extern "C" - * around the header. - */ - - -/** - * G_FILE_ERROR: - * - * Error domain for file operations. Errors in this domain will - * be from the #GFileError enumeration. See #GError for information - * on error domains. - */ - - -/** - * G_GINT16_FORMAT: - * - * This is the platform dependent conversion specifier for scanning and - * printing values of type #gint16. 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. - * - * |[<!-- language="C" --> - * 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"; - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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 - * - * |[<!-- language="C" --> - * - * // 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 - * ]| - * - * |[<!-- language="C" -- - * static void - * test_deprecated_function (void) - * { - * G_GNUC_BEGIN_IGNORE_DEPRECATIONS - * g_assert_cmpint (my_mistake (), ==, 42); - * G_GNUC_END_IGNORE_DEPRECATIONS - * } - * ]| - * - * Since: 2.32 - */ - - -/** - * G_GNUC_CHECK_VERSION: - * @major: major version to check against - * @minor: minor version to check against - * - * Expands to a check for a compiler with __GNUC__ defined and a version - * greater than or equal to the major and minor numbers provided. For example, - * the following would only match on compilers such as GCC 4.8 or newer. - * - * |[<!-- language="C" --> - * #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. - * - * |[<!-- language="C" --> - * 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. - * - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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<<G_LOG_LEVEL_USER_SHIFT are used by GLib. - * Higher bits can be used for user-defined log levels. - */ - - -/** - * G_MAXDOUBLE: - * - * The maximum value which can be held in a #gdouble. - */ - - -/** - * G_MAXFLOAT: - * - * The maximum value which can be held in a #gfloat. - */ - - -/** - * G_MAXINT: - * - * The maximum value which can be held in a #gint. - */ - - -/** - * G_MAXINT16: - * - * The maximum value which can be held in a #gint16. - * - * Since: 2.4 - */ - - -/** - * G_MAXINT32: - * - * The maximum value which can be held in a #gint32. - * - * Since: 2.4 - */ - - -/** - * G_MAXINT64: - * - * The maximum value which can be held in a #gint64. - */ - - -/** - * G_MAXINT8: - * - * The maximum value which can be held in a #gint8. - * - * Since: 2.4 - */ - - -/** - * G_MAXLONG: - * - * The maximum value which can be held in a #glong. - */ - - -/** - * G_MAXOFFSET: - * - * The maximum value which can be held in a #goffset. - */ - - -/** - * G_MAXSHORT: - * - * The maximum value which can be held in a #gshort. - */ - - -/** - * G_MAXSIZE: - * - * The maximum value which can be held in a #gsize. - * - * Since: 2.4 - */ - - -/** - * G_MAXSSIZE: - * - * The maximum value which can be held in a #gssize. - * - * Since: 2.14 - */ - - -/** - * G_MAXUINT: - * - * The maximum value which can be held in a #guint. - */ - - -/** - * G_MAXUINT16: - * - * The maximum value which can be held in a #guint16. - * - * Since: 2.4 - */ - - -/** - * G_MAXUINT32: - * - * The maximum value which can be held in a #guint32. - * - * Since: 2.4 - */ - - -/** - * G_MAXUINT64: - * - * The maximum value which can be held in a #guint64. - */ - - -/** - * G_MAXUINT8: - * - * The maximum value which can be held in a #guint8. - * - * Since: 2.4 - */ - - -/** - * G_MAXULONG: - * - * The maximum value which can be held in a #gulong. - */ - - -/** - * G_MAXUSHORT: - * - * The maximum value which can be held in a #gushort. - */ - - -/** - * G_MINDOUBLE: - * - * The minimum positive value which can be held in a #gdouble. - * - * If you are interested in the smallest value which can be held - * in a #gdouble, use -%G_MAXDOUBLE. - */ - - -/** - * G_MINFLOAT: - * - * The minimum positive value which can be held in a #gfloat. - * - * If you are interested in the smallest value which can be held - * in a #gfloat, use -%G_MAXFLOAT. - */ - - -/** - * G_MININT: - * - * The minimum value which can be held in a #gint. - */ - - -/** - * G_MINLONG: - * - * The minimum value which can be held in a #glong. - */ - - -/** - * G_MINOFFSET: - * - * The minimum value which can be held in a #goffset. - */ - - -/** - * G_MINSHORT: - * - * The minimum value which can be held in a #gshort. - */ - - -/** - * G_MINSSIZE: - * - * The minimum value which can be held in a #gssize. - * - * Since: 2.14 - */ - - -/** - * G_N_ELEMENTS: - * @arr: the array - * - * Determines the number of elements in an array. The array must be - * declared so the compiler knows its size at compile-time; this - * macro will not work on an array allocated on the heap, only static - * arrays or arrays on the stack. - */ - - -/** - * G_ONCE_INIT: - * - * A #GOnce must be initialized with this macro before it can be used. - * - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * #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: - * |[<!-- language="C" --> - * 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. - * - * |[<!-- language="C" --> - * 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. - * - * |[<!-- language="C" --> - * #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: - * - * |[<!-- language="C" --> - * #define AGE 27 - * const gchar *greeting = G_STRINGIFY (AGE) " today!"; - * ]| - * - * is transformed by the preprocessor into (code equivalent to): - * - * |[<!-- language="C" --> - * 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. - * - * |[<!-- language="C" --> - * 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. - * - * |[<!-- language="C" --> - * { - * 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. - * |[<!-- language="C" --> - * { - * 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: - * - * |[<!-- language="C" --> - * 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(): - * - * |[<!-- language="C" --> - * // 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: - * - * |[<!-- language="C" --> - * 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(): - * - * |[<!-- language="C" --> - * 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(): - * - * |[<!-- language="C" --> - * 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(): - * - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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 - * <xbel> root element; each bookmark is stored inside a - * <bookmark> 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 - * <metadata> 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) - * - *  - * - * ## 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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. - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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(): - * |[<!-- language="C" --> - * 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 <NAMESPACE>_<MODULE>_ERROR, - * for example %G_SPAWN_ERROR or %G_THREAD_ERROR: - * |[<!-- language="C" --> - * #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 - * <namespace>_<module>_error_quark, - * for example g_spawn_error_quark() or g_thread_error_quark(). - * - * - The error codes are in an enumeration called - * <Namespace><Module>Error; - * for example, #GThreadError or #GSpawnError. - * - * - Members of the error code enumeration are called - * <NAMESPACE>_<MODULE>_ERROR_<CODE>, - * 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 <NAMESPACE>_<MODULE>_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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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 - * `<glib/gi18n.h>`. For use in a library, you must include - * `<glib/gi18n-lib.h>` - * after defining the %GETTEXT_PACKAGE macro suitably for your library: - * |[<!-- language="C" --> - * #define GETTEXT_PACKAGE "gtk20" - * #include <glib/gi18n-lib.h> - * ]| - * 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: - * |[<!-- language="C" --> - * #include <glib/gi18n.h> - * #include <locale.h> - * - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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. - * - *  - * - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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. - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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(): - * - * |[<!-- language="C" --> - * // 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: - * - * |[<!-- language="C" --> - * 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(): - * - * |[<!-- language="C" --> - * 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(): - * - * |[<!-- language="C" --> - * 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(): - * - * |[<!-- language="C" --> - * 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: - * - * |[<!-- language="C" --> - * 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(): - * |[<!-- language="C" --> - * 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 `<glib/gprintf.h>` 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 - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * #include <glib.h> - * #include <locale.h> - * - * 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.: - * - * |[<!-- language="plain" --> - * 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: - * - * |[<!-- language="plain" --> - * 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`: - * - * |[<!-- language="plain" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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. - * - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * ... - * 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. - * - * |[<!-- language="C" --> - * 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. - * - * |[<!-- language="C" --> - * 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. - * - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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): - * - * |[<!-- language="C" --> - * 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: - * |[<!-- language="C" --> - * 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 <date><sep><time><tz> are supported, with - * some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as - * mentioned below. - * - * Note that as #GDateTime "is oblivious to leap seconds", leap seconds information - * in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as - * `23:59:59`. - * - * <sep> is the separator and can be either 'T', 't' or ' '. The latter two - * separators are an extension from - * [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6). - * - * <date> is in the form: - * - * - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24. - * - `YYYYMMDD` - Same as above without dividers. - * - `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237. - * - `YYYYDDD` - Same as above without dividers. - * - `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7, - * e.g. 2016-W34-3. - * - `YYYYWwwD` - Same as above without dividers. - * - * <time> is in the form: - * - * - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123. - * - `hhmmss(.sss)` - Same as above without dividers. - * - * <tz> is an optional timezone suffix of the form: - * - * - `Z` - UTC. - * - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00. - * - `+hh` or `-hh` - Offset from UTC in hours, e.g. +12. - * - * If the timezone is not provided in @text it must be provided in @default_tz - * (this field is otherwise ignored). - * - * This call can fail (returning %NULL) if @text is not a valid ISO 8601 - * formatted string. - * - * 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.56 - */ - - -/** - * g_date_time_new_from_timeval_local: (constructor) - * @tv: a #GTimeVal - * - * Creates a #GDateTime corresponding to the given #GTimeVal @tv in the - * local time zone. - * - * The time contained in a #GTimeVal is always stored in the form of - * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the - * local time offset. - * - * This call can fail (returning %NULL) if @tv represents a time outside - * of the supported range of #GDateTime. - * - * 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 - * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use - * g_date_time_new_from_unix_local() instead. - */ - - -/** - * g_date_time_new_from_timeval_utc: (constructor) - * @tv: a #GTimeVal - * - * Creates a #GDateTime corresponding to the given #GTimeVal @tv in UTC. - * - * The time contained in a #GTimeVal is always stored in the form of - * seconds elapsed since 1970-01-01 00:00:00 UTC. - * - * This call can fail (returning %NULL) if @tv represents a time outside - * of the supported range of #GDateTime. - * - * 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 - * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use - * g_date_time_new_from_unix_utc() instead. - */ - - -/** - * g_date_time_new_from_unix_local: (constructor) - * @t: the Unix time - * - * Creates a #GDateTime corresponding to the given Unix time @t in the - * local time zone. - * - * Unix time is the number of seconds that have elapsed since 1970-01-01 - * 00:00:00 UTC, regardless of the local time offset. - * - * This call can fail (returning %NULL) if @t represents a time outside - * of the supported range of #GDateTime. - * - * 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_unix_utc: (constructor) - * @t: the Unix time - * - * Creates a #GDateTime corresponding to the given Unix time @t in UTC. - * - * Unix time is the number of seconds that have elapsed since 1970-01-01 - * 00:00:00 UTC. - * - * This call can fail (returning %NULL) if @t represents a time outside - * of the supported range of #GDateTime. - * - * 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_local: (constructor) - * @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 local time zone. - * - * This call is equivalent to calling g_date_time_new() with the time - * zone returned by g_time_zone_new_local(). - * - * Returns: (transfer full) (nullable): a #GDateTime, or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_new_now: (constructor) - * @tz: a #GTimeZone - * - * Creates a #GDateTime corresponding to this exact instant in the given - * time zone @tz. The time is as accurate as the system allows, to a - * maximum accuracy of 1 microsecond. - * - * This function will always succeed unless GLib is still being used after the - * year 9999. - * - * 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_now_local: (constructor) - * - * Creates a #GDateTime corresponding to this exact instant in the local - * time zone. - * - * This is equivalent to calling g_date_time_new_now() with the time - * zone returned by g_time_zone_new_local(). - * - * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_new_now_utc: (constructor) - * - * Creates a #GDateTime corresponding to this exact instant in UTC. - * - * This is equivalent to calling g_date_time_new_now() with the time - * zone returned by g_time_zone_new_utc(). - * - * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_new_utc: (constructor) - * @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 - * UTC. - * - * This call is equivalent to calling g_date_time_new() with the time - * zone returned by g_time_zone_new_utc(). - * - * Returns: (transfer full) (nullable): a #GDateTime, or %NULL - * Since: 2.26 - */ - - -/** - * g_date_time_ref: - * @datetime: a #GDateTime - * - * Atomically increments the reference count of @datetime by one. - * - * Returns: the #GDateTime with the reference count increased - * Since: 2.26 - */ - - -/** - * g_date_time_to_local: - * @datetime: a #GDateTime - * - * Creates a new #GDateTime corresponding to the same instant in time as - * @datetime, but in the local time zone. - * - * This call is equivalent to calling g_date_time_to_timezone() with the - * time zone returned by g_time_zone_new_local(). - * - * 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_to_timeval: - * @datetime: a #GDateTime - * @tv: a #GTimeVal to modify - * - * Stores the instant in time that @datetime represents into @tv. - * - * The time contained in a #GTimeVal is always stored in the form of - * seconds elapsed since 1970-01-01 00:00:00 UTC, regardless of the time - * zone associated with @datetime. - * - * On systems where 'long' is 32bit (ie: all 32bit systems and all - * Windows systems), a #GTimeVal is incapable of storing the entire - * range of values that #GDateTime is capable of expressing. On those - * systems, this function returns %FALSE to indicate that the time is - * out of range. - * - * On systems where 'long' is 64bit, this function never fails. - * - * Returns: %TRUE if successful, else %FALSE - * Since: 2.26 - * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use - * g_date_time_to_unix() instead. - */ - - -/** - * g_date_time_to_timezone: - * @datetime: a #GDateTime - * @tz: the new #GTimeZone - * - * Create a new #GDateTime corresponding to the same instant in time as - * @datetime, but in the time zone @tz. - * - * This call can fail in the case that the time goes out of bounds. For - * example, converting 0001-01-01 00:00:00 UTC to a time zone west of - * Greenwich will fail (due to the year 0 being out of range). - * - * 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_to_unix: - * @datetime: a #GDateTime - * - * Gives the Unix time corresponding to @datetime, rounding down to the - * nearest second. - * - * Unix time is the number of seconds that have elapsed since 1970-01-01 - * 00:00:00 UTC, regardless of the time zone associated with @datetime. - * - * Returns: the Unix time corresponding to @datetime - * Since: 2.26 - */ - - -/** - * g_date_time_to_utc: - * @datetime: a #GDateTime - * - * Creates a new #GDateTime corresponding to the same instant in time as - * @datetime, but in UTC. - * - * This call is equivalent to calling g_date_time_to_timezone() with the - * time zone returned by g_time_zone_new_utc(). - * - * 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_unref: - * @datetime: a #GDateTime - * - * Atomically decrements the reference count of @datetime by one. - * - * When the reference count reaches zero, the resources allocated by - * @datetime are freed - * - * Since: 2.26 - */ - - -/** - * g_date_to_struct_tm: - * @date: a #GDate to set the struct tm from - * @tm: (not nullable): struct tm to fill - * - * Fills in the date-related bits of a struct tm using the @date value. - * Initializes the non-date parts with something safe but meaningless. - */ - - -/** - * g_date_valid: - * @date: a #GDate to check - * - * Returns %TRUE if the #GDate represents an existing day. The date must not - * contain garbage; it should have been initialized with g_date_clear() - * if it wasn't allocated by one of the g_date_new() variants. - * - * Returns: Whether the date is valid - */ - - -/** - * g_date_valid_day: - * @day: day to check - * - * Returns %TRUE if the day of the month is valid (a day is valid if it's - * between 1 and 31 inclusive). - * - * Returns: %TRUE if the day is valid - */ - - -/** - * g_date_valid_dmy: - * @day: day - * @month: month - * @year: year - * - * Returns %TRUE if the day-month-year triplet forms a valid, existing day - * in the range of days #GDate understands (Year 1 or later, no more than - * a few thousand years in the future). - * - * Returns: %TRUE if the date is a valid one - */ - - -/** - * g_date_valid_julian: - * @julian_date: Julian day to check - * - * Returns %TRUE if the Julian day is valid. Anything greater than zero - * is basically a valid Julian, though there is a 32-bit limit. - * - * Returns: %TRUE if the Julian day is valid - */ - - -/** - * g_date_valid_month: - * @month: month - * - * Returns %TRUE if the month value is valid. The 12 #GDateMonth - * enumeration values are the only valid months. - * - * Returns: %TRUE if the month is valid - */ - - -/** - * g_date_valid_weekday: - * @weekday: weekday - * - * Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration - * values are the only valid weekdays. - * - * Returns: %TRUE if the weekday is valid - */ - - -/** - * g_date_valid_year: - * @year: year - * - * Returns %TRUE if the year is valid. Any year greater than 0 is valid, - * though there is a 16-bit limit to what #GDate will understand. - * - * Returns: %TRUE if the year is valid - */ - - -/** - * g_dcgettext: - * @domain: (nullable): the translation domain to use, or %NULL to use - * the domain set with textdomain() - * @msgid: message to translate - * @category: a locale category - * - * This is a variant of g_dgettext() that allows specifying a locale - * category instead of always using `LC_MESSAGES`. See g_dgettext() for - * more information about how this functions differs from calling - * dcgettext() directly. - * - * Returns: the translated string for the given locale category - * Since: 2.26 - */ - - -/** - * g_debug: - * @...: format string, followed by parameters to insert - * into the format string (as with printf()) - * - * A convenience function/macro to log a debug message. 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. - * - * Such messages are suppressed by the g_log_default_handler() and - * g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is - * set appropriately. - * - * If structured logging is enabled, this will use g_log_structured(); - * otherwise it will use g_log(). See - * [Using Structured Logging][using-structured-logging]. - * - * Since: 2.6 - */ - - -/** - * g_dgettext: - * @domain: (nullable): the translation domain to use, or %NULL to use - * the domain set with textdomain() - * @msgid: message to translate - * - * This function is a wrapper of dgettext() which does not translate - * the message if the default domain as set with textdomain() has no - * translations for the current locale. - * - * The advantage of using this function over dgettext() proper is that - * libraries using this function (like GTK+) will not use translations - * if the application using the library does not have translations for - * the current locale. This results in a consistent English-only - * interface instead of one having partial translations. For this - * feature to work, the call to textdomain() and setlocale() should - * precede any g_dgettext() invocations. For GTK+, it means calling - * textdomain() before gtk_init or its variants. - * - * This function disables translations if and only if upon its first - * call all the following conditions hold: - * - * - @domain is not %NULL - * - * - textdomain() has been called to set a default text domain - * - * - there is no translations available for the default text domain - * and the current locale - * - * - current locale is not "C" or any English locales (those - * starting with "en_") - * - * Note that this behavior may not be desired for example if an application - * has its untranslated messages in a language other than English. In those - * cases the application should call textdomain() after initializing GTK+. - * - * Applications should normally not use this function directly, - * but use the _() macro for translations. - * - * Returns: The translated string - * Since: 2.18 - */ - - -/** - * g_dir_close: - * @dir: a #GDir* created by g_dir_open() - * - * Closes the directory and deallocates all related resources. - */ - - -/** - * g_dir_make_tmp: - * @tmpl: (type filename) (nullable): Template for directory name, - * as in g_mkdtemp(), basename only, or %NULL for a default template - * @error: return location for a #GError - * - * Creates a subdirectory in the preferred directory for temporary - * files (as returned by g_get_tmp_dir()). - * - * @tmpl should be a string in the GLib file name encoding containing - * a sequence of six 'X' characters, as the parameter to g_mkstemp(). - * However, unlike these functions, the template should only be a - * basename, no directory components are allowed. If template is - * %NULL, a default template is used. - * - * Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not - * modified, and might thus be a read-only literal string. - * - * Returns: (type filename): The actual name used. This string - * should be freed with g_free() when not needed any longer and is - * is in the GLib file name encoding. In case of errors, %NULL is - * returned and @error will be set. - * Since: 2.30 - */ - - -/** - * g_dir_open: - * @path: the path to the directory you are interested in. On Unix - * in the on-disk encoding. On Windows in UTF-8 - * @flags: Currently must be set to 0. Reserved for future use. - * @error: return location for a #GError, or %NULL. - * If non-%NULL, an error will be set if and only if - * g_dir_open() fails. - * - * Opens a directory for reading. The names of the files in the - * directory can then be retrieved using g_dir_read_name(). Note - * that the ordering is not defined. - * - * Returns: a newly allocated #GDir on success, %NULL on failure. - * If non-%NULL, you must free the result with g_dir_close() - * when you are finished with it. - */ - - -/** - * g_dir_read_name: - * @dir: a #GDir* created by g_dir_open() - * - * Retrieves the name of another entry in the directory, or %NULL. - * The order of entries returned from this function is not defined, - * and may vary by file system or other operating-system dependent - * factors. - * - * %NULL may also be returned in case of errors. On Unix, you can - * check `errno` to find out if %NULL was returned because of an error. - * - * On Unix, the '.' and '..' entries are omitted, and the returned - * name is in the on-disk encoding. - * - * On Windows, as is true of all GLib functions which operate on - * filenames, the returned name is in UTF-8. - * - * Returns: (type filename): The entry's name or %NULL if there are no - * more entries. The return value is owned by GLib and - * must not be modified or freed. - */ - - -/** - * g_dir_rewind: - * @dir: a #GDir* created by g_dir_open() - * - * Resets the given directory. The next call to g_dir_read_name() - * will return the first entry again. - */ - - -/** - * g_direct_equal: - * @v1: (nullable): a key - * @v2: (nullable): a key to compare with @v1 - * - * Compares two #gpointer arguments and returns %TRUE if they are equal. - * It can be passed to g_hash_table_new() as the @key_equal_func - * parameter, when using opaque pointers compared by pointer value as - * keys in a #GHashTable. - * - * This equality function is also appropriate for keys that are integers - * stored in pointers, such as `GINT_TO_POINTER (n)`. - * - * Returns: %TRUE if the two keys match. - */ - - -/** - * g_direct_hash: - * @v: (nullable): a #gpointer key - * - * Converts a gpointer to a hash value. - * It can be passed to g_hash_table_new() as the @hash_func parameter, - * when using opaque pointers compared by pointer value as keys in a - * #GHashTable. - * - * This hash function is also appropriate for keys that are integers - * stored in pointers, such as `GINT_TO_POINTER (n)`. - * - * Returns: a hash value corresponding to the key. - */ - - -/** - * g_dirname: - * @file_name: (type filename): the name of the file - * - * Gets the directory components of a file name. - * - * If the file name has no directory components "." is returned. - * The returned string should be freed when no longer needed. - * - * Returns: (type filename): the directory components of the file - * Deprecated: use g_path_get_dirname() instead - */ - - -/** - * g_dngettext: - * @domain: (nullable): the translation domain to use, or %NULL to use - * the domain set with textdomain() - * @msgid: message to translate - * @msgid_plural: plural form of the message - * @n: the quantity for which translation is needed - * - * This function is a wrapper of dngettext() which does not translate - * the message if the default domain as set with textdomain() has no - * translations for the current locale. - * - * See g_dgettext() for details of how this differs from dngettext() - * proper. - * - * Returns: The translated string - * Since: 2.18 - */ - - -/** - * g_double_equal: - * @v1: (not nullable): a pointer to a #gdouble key - * @v2: (not nullable): a pointer to a #gdouble key to compare with @v1 - * - * Compares the two #gdouble values being pointed to and returns - * %TRUE if they are equal. - * It can be passed to g_hash_table_new() as the @key_equal_func - * parameter, when using non-%NULL pointers to doubles as keys in a - * #GHashTable. - * - * Returns: %TRUE if the two keys match. - * Since: 2.22 - */ - - -/** - * g_double_hash: - * @v: (not nullable): a pointer to a #gdouble key - * - * Converts a pointer to a #gdouble to a hash value. - * It can be passed to g_hash_table_new() as the @hash_func parameter, - * It can be passed to g_hash_table_new() as the @hash_func parameter, - * when using non-%NULL pointers to doubles as keys in a #GHashTable. - * - * Returns: a hash value corresponding to the key. - * Since: 2.22 - */ - - -/** - * g_dpgettext: - * @domain: (nullable): the translation domain to use, or %NULL to use - * the domain set with textdomain() - * @msgctxtid: a combined message context and message id, separated - * by a \004 character - * @msgidoffset: the offset of the message id in @msgctxid - * - * This function is a variant of g_dgettext() which supports - * a disambiguating message context. GNU gettext uses the - * '\004' character to separate the message context and - * message id in @msgctxtid. - * If 0 is passed as @msgidoffset, this function will fall back to - * trying to use the deprecated convention of using "|" as a separation - * character. - * - * This uses g_dgettext() internally. See that functions for differences - * with dgettext() proper. - * - * Applications should normally not use this function directly, - * but use the C_() macro for translations with context. - * - * Returns: The translated string - * Since: 2.16 - */ - - -/** - * g_dpgettext2: - * @domain: (nullable): the translation domain to use, or %NULL to use - * the domain set with textdomain() - * @context: the message context - * @msgid: the message - * - * This function is a variant of g_dgettext() which supports - * a disambiguating message context. GNU gettext uses the - * '\004' character to separate the message context and - * message id in @msgctxtid. - * - * This uses g_dgettext() internally. See that functions for differences - * with dgettext() proper. - * - * This function differs from C_() in that it is not a macro and - * thus you may use non-string-literals as context and msgid arguments. - * - * Returns: The translated string - * Since: 2.18 - */ - - -/** - * g_environ_getenv: - * @envp: (nullable) (array zero-terminated=1) (transfer none) (element-type filename): - * an environment list (eg, as returned from g_get_environ()), or %NULL - * for an empty environment list - * @variable: (type filename): the environment variable to get - * - * Returns the value of the environment variable @variable in the - * provided list @envp. - * - * Returns: (type filename): the value of the environment variable, or %NULL if - * the environment variable is not set in @envp. The returned - * string is owned by @envp, and will be freed if @variable is - * set or unset again. - * Since: 2.32 - */ - - -/** - * g_environ_setenv: - * @envp: (nullable) (array zero-terminated=1) (element-type filename) (transfer full): - * an environment list that can be freed using g_strfreev() (e.g., as - * returned from g_get_environ()), or %NULL for an empty - * environment list - * @variable: (type filename): the environment variable to set, must not - * contain '=' - * @value: (type filename): the value for to set the variable to - * @overwrite: whether to change the variable if it already exists - * - * Sets the environment variable @variable in the provided list - * @envp to @value. - * - * Returns: (array zero-terminated=1) (element-type filename) (transfer full): - * the updated environment list. Free it using g_strfreev(). - * Since: 2.32 - */ - - -/** - * g_environ_unsetenv: - * @envp: (nullable) (array zero-terminated=1) (element-type filename) (transfer full): - * an environment list that can be freed using g_strfreev() (e.g., as - * returned from g_get_environ()), or %NULL for an empty environment list - * @variable: (type filename): the environment variable to remove, must not - * contain '=' - * - * Removes the environment variable @variable from the provided - * environment @envp. - * - * Returns: (array zero-terminated=1) (element-type filename) (transfer full): - * the updated environment list. Free it using g_strfreev(). - * Since: 2.32 - */ - - -/** - * g_error: - * @...: format string, followed by parameters to insert - * into the format string (as with printf()) - * - * A convenience function/macro to log an error message. The message should - * typically *not* be translated to the user's language. - * - * This is not intended for end user error reporting. Use of #GError is - * preferred for that instead, as it allows calling functions to perform actions - * conditional on the type of error. - * - * Error messages are always fatal, resulting in a call to G_BREAKPOINT() - * to terminate the application. This function will - * result in a core dump; don't use it for errors you expect. - * Using this function indicates a bug in your program, i.e. - * an assertion failure. - * - * 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_error_copy: - * @error: a #GError - * - * Makes a copy of @error. - * - * Returns: a new #GError - */ - - -/** - * g_error_domain_register: - * @error_type_name: string to create a #GQuark from - * @error_type_private_size: size of the private error data in bytes - * @error_type_init: function initializing fields of the private error data - * @error_type_copy: function copying fields of the private error data - * @error_type_clear: function freeing fields of the private error data - * - * This function registers an extended #GError domain. - * @error_type_name will be duplicated. Otherwise does the same as - * g_error_domain_register_static(). - * - * Returns: #GQuark representing the error domain - * Since: 2.68 - */ - - -/** - * g_error_domain_register_static: - * @error_type_name: static string to create a #GQuark from - * @error_type_private_size: size of the private error data in bytes - * @error_type_init: function initializing fields of the private error data - * @error_type_copy: function copying fields of the private error data - * @error_type_clear: function freeing fields of the private error data - * - * This function registers an extended #GError domain. - * - * @error_type_name should not be freed. @error_type_private_size must - * be greater than 0. - * - * @error_type_init receives an initialized #GError and should then initialize - * the private data. - * - * @error_type_copy is a function that receives both original and a copy - * #GError and should copy the fields of the private error data. The standard - * #GError fields are already handled. - * - * @error_type_clear receives the pointer to the error, and it should free the - * fields of the private error data. It should not free the struct itself though. - * - * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it - * already takes care of passing valid information to this function. - * - * Returns: #GQuark representing the error domain - * Since: 2.68 - */ - - -/** - * g_error_free: - * @error: a #GError - * - * Frees a #GError and associated resources. - */ - - -/** - * g_error_matches: - * @error: (nullable): a #GError - * @domain: an error domain - * @code: an error code - * - * Returns %TRUE if @error matches @domain and @code, %FALSE - * otherwise. In particular, when @error is %NULL, %FALSE will - * be returned. - * - * If @domain contains a `FAILED` (or otherwise generic) error code, - * you should generally not check for it explicitly, but should - * instead treat any not-explicitly-recognized error code as being - * equivalent to the `FAILED` code. This way, if the domain is - * extended in the future to provide a more specific error code for - * a certain case, your code will still work. - * - * Returns: whether @error has @domain and @code - */ - - -/** - * g_error_new: - * @domain: error domain - * @code: error code - * @format: printf()-style format for error message - * @...: parameters for message format - * - * Creates a new #GError with the given @domain and @code, - * and a message formatted with @format. - * - * Returns: a new #GError - */ - - -/** - * g_error_new_literal: - * @domain: error domain - * @code: error code - * @message: error message - * - * Creates a new #GError; unlike g_error_new(), @message is - * not a printf()-style format string. Use this function if - * @message contains text you don't have control over, - * that could include printf() escape sequences. - * - * Returns: a new #GError - */ - - -/** - * g_error_new_valist: - * @domain: error domain - * @code: error code - * @format: printf()-style format for error message - * @args: #va_list of parameters for the message format - * - * Creates a new #GError with the given @domain and @code, - * and a message formatted with @format. - * - * Returns: a new #GError - * Since: 2.22 - */ - - -/** - * g_file_error_from_errno: - * @err_no: an "errno" value - * - * Gets a #GFileError constant based on the passed-in @err_no. - * - * For example, if you pass in `EEXIST` this function returns - * %G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably - * assume that all #GFileError values will exist. - * - * Normally a #GFileError value goes into a #GError returned - * from a function that manipulates files. So you would use - * g_file_error_from_errno() when constructing a #GError. - * - * Returns: #GFileError corresponding to the given @err_no - */ - - -/** - * g_file_get_contents: - * @filename: (type filename): name of a file to read contents from, in the GLib file name encoding - * @contents: (out) (array length=length) (element-type guint8): location to store an allocated string, use g_free() to free - * the returned string - * @length: (nullable): location to store length in bytes of the contents, or %NULL - * @error: return location for a #GError, or %NULL - * - * Reads an entire file into allocated memory, with good error - * checking. - * - * If the call was successful, it returns %TRUE and sets @contents to the file - * contents and @length to the length of the file contents in bytes. The string - * stored in @contents will be nul-terminated, so for text files you can pass - * %NULL for the @length argument. If the call was not successful, it returns - * %FALSE and sets @error. The error domain is #G_FILE_ERROR. Possible error - * codes are those in the #GFileError enumeration. In the error case, - * @contents is set to %NULL and @length is set to zero. - * - * Returns: %TRUE on success, %FALSE if an error occurred - */ - - -/** - * g_file_open_tmp: - * @tmpl: (type filename) (nullable): Template for file name, as in - * g_mkstemp(), basename only, or %NULL for a default template - * @name_used: (out) (type filename): location to store actual name used, - * or %NULL - * @error: return location for a #GError - * - * Opens a file for writing in the preferred directory for temporary - * files (as returned by g_get_tmp_dir()). - * - * @tmpl should be a string in the GLib file name encoding containing - * a sequence of six 'X' characters, as the parameter to g_mkstemp(). - * However, unlike these functions, the template should only be a - * basename, no directory components are allowed. If template is - * %NULL, a default template is used. - * - * Note that in contrast to g_mkstemp() (and mkstemp()) @tmpl is not - * modified, and might thus be a read-only literal string. - * - * Upon success, and if @name_used is non-%NULL, the actual name used - * is returned in @name_used. This string should be freed with g_free() - * when not needed any longer. The returned name is in the GLib file - * name encoding. - * - * Returns: A file handle (as from open()) to the file opened for - * reading and writing. The file is opened in binary mode on platforms - * where there is a difference. The file handle should be closed with - * close(). In case of errors, -1 is returned and @error will be set. - */ - - -/** - * g_file_read_link: - * @filename: (type filename): the symbolic link - * @error: return location for a #GError - * - * Reads the contents of the symbolic link @filename like the POSIX - * readlink() function. The returned string is in the encoding used - * for filenames. Use g_filename_to_utf8() to convert it to UTF-8. - * - * Returns: (type filename): A newly-allocated string with the contents of - * the symbolic link, or %NULL if an error occurred. - * Since: 2.4 - */ - - -/** - * g_file_set_contents: - * @filename: (type filename): name of a file to write @contents to, in the GLib file name - * encoding - * @contents: (array length=length) (element-type guint8): string to write to the file - * @length: length of @contents, or -1 if @contents is a nul-terminated string - * @error: return location for a #GError, or %NULL - * - * Writes all of @contents to a file named @filename. This is a convenience - * wrapper around calling g_file_set_contents_full() with `flags` set to - * `G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and - * `mode` set to `0666`. - * - * Returns: %TRUE on success, %FALSE if an error occurred - * Since: 2.8 - */ - - -/** - * g_file_set_contents_full: - * @filename: (type filename): name of a file to write @contents to, in the GLib file name - * encoding - * @contents: (array length=length) (element-type guint8): string to write to the file - * @length: length of @contents, or -1 if @contents is a nul-terminated string - * @flags: flags controlling the safety vs speed of the operation - * @mode: file mode, as passed to `open()`; typically this will be `0666` - * @error: return location for a #GError, or %NULL - * - * Writes all of @contents to a file named @filename, with good error checking. - * If a file called @filename already exists it will be overwritten. - * - * @flags control the properties of the write operation: whether it’s atomic, - * and what the tradeoff is between returning quickly or being resilient to - * system crashes. - * - * As this function performs file I/O, it is recommended to not call it anywhere - * where blocking would cause problems, such as in the main loop of a graphical - * application. In particular, if @flags has any value other than - * %G_FILE_SET_CONTENTS_NONE then this function may call `fsync()`. - * - * If %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the operation is atomic - * in the sense that it is first written to a temporary file which is then - * renamed to the final name. - * - * Notes: - * - * - On UNIX, if @filename already exists hard links to @filename will break. - * Also since the file is recreated, existing permissions, access control - * lists, metadata etc. may be lost. If @filename is a symbolic link, - * the link itself will be replaced, not the linked file. - * - * - On UNIX, if @filename already exists and is non-empty, and if the system - * supports it (via a journalling filesystem or equivalent), and if - * %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the `fsync()` call (or - * equivalent) will be used to ensure atomic replacement: @filename - * will contain either its old contents or @contents, even in the face of - * system power loss, the disk being unsafely removed, etc. - * - * - On UNIX, if @filename does not already exist or is empty, there is a - * possibility that system power loss etc. after calling this function will - * leave @filename empty or full of NUL bytes, depending on the underlying - * filesystem, unless %G_FILE_SET_CONTENTS_DURABLE and - * %G_FILE_SET_CONTENTS_CONSISTENT are set in @flags. - * - * - On Windows renaming a file will not remove an existing file with the - * new name, so on Windows there is a race condition between the existing - * file being removed and the temporary file being renamed. - * - * - On Windows there is no way to remove a file that is open to some - * process, or mapped into memory. Thus, this function will fail if - * @filename already exists and is open. - * - * If the call was successful, it returns %TRUE. If the call was not successful, - * it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR. - * Possible error codes are those in the #GFileError enumeration. - * - * Note that the name for the temporary file is constructed by appending up - * to 7 characters to @filename. - * - * If the file didn’t exist before and is created, it will be given the - * permissions from @mode. Otherwise, the permissions of the existing file may - * be changed to @mode depending on @flags, or they may remain unchanged. - * - * Returns: %TRUE on success, %FALSE if an error occurred - * Since: 2.66 - */ - - -/** - * g_file_test: - * @filename: (type filename): a filename to test in the - * GLib file name encoding - * @test: bitfield of #GFileTest flags - * - * Returns %TRUE if any of the tests in the bitfield @test are - * %TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)` - * will return %TRUE if the file exists; the check whether it's a - * directory doesn't matter since the existence test is %TRUE. With - * the current set of available tests, there's no point passing in - * more than one test at a time. - * - * Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links, - * so for a symbolic link to a regular file g_file_test() will return - * %TRUE for both %G_FILE_TEST_IS_SYMLINK and %G_FILE_TEST_IS_REGULAR. - * - * Note, that for a dangling symbolic link g_file_test() will return - * %TRUE for %G_FILE_TEST_IS_SYMLINK and %FALSE for all other flags. - * - * You should never use g_file_test() to test whether it is safe - * to perform an operation, because there is always the possibility - * of the condition changing before you actually perform the operation. - * For example, you might think you could use %G_FILE_TEST_IS_SYMLINK - * to know whether it is safe to write to a file without being - * tricked into writing into a different location. It doesn't work! - * |[<!-- language="C" --> - * // DON'T DO THIS - * if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) - * { - * fd = g_open (filename, O_WRONLY); - * // write to fd - * } - * ]| - * - * Another thing to note is that %G_FILE_TEST_EXISTS and - * %G_FILE_TEST_IS_EXECUTABLE are implemented using the access() - * system call. This usually doesn't matter, but if your program - * is setuid or setgid it means that these tests will give you - * the answer for the real user ID and group ID, rather than the - * effective user ID and group ID. - * - * On Windows, there are no symlinks, so testing for - * %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for - * %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and - * its name indicates that it is executable, checking for well-known - * extensions and those listed in the `PATHEXT` environment variable. - * - * Returns: whether a test was %TRUE - */ - - -/** - * g_filename_display_basename: - * @filename: (type filename): an absolute pathname in the - * GLib file name encoding - * - * Returns the display basename for the particular filename, guaranteed - * to be valid UTF-8. The display name might not be identical to the filename, - * for instance there might be problems converting it to UTF-8, and some files - * can be translated in the display. - * - * If GLib cannot make sense of the encoding of @filename, as a last resort it - * replaces unknown characters with U+FFFD, the Unicode replacement character. - * You can search the result for the UTF-8 encoding of this character (which is - * "\357\277\275" in octal notation) to find out if @filename was in an invalid - * encoding. - * - * You must pass the whole absolute pathname to this functions so that - * translation of well known locations can be done. - * - * This function is preferred over g_filename_display_name() if you know the - * whole path, as it allows translation. - * - * Returns: a newly allocated string containing - * a rendition of the basename of the filename in valid UTF-8 - * Since: 2.6 - */ - - -/** - * g_filename_display_name: - * @filename: (type filename): a pathname hopefully in the - * GLib file name encoding - * - * Converts a filename into a valid UTF-8 string. The conversion is - * not necessarily reversible, so you should keep the original around - * and use the return value of this function only for display purposes. - * Unlike g_filename_to_utf8(), the result is guaranteed to be non-%NULL - * even if the filename actually isn't in the GLib file name encoding. - * - * If GLib cannot make sense of the encoding of @filename, as a last resort it - * replaces unknown characters with U+FFFD, the Unicode replacement character. - * You can search the result for the UTF-8 encoding of this character (which is - * "\357\277\275" in octal notation) to find out if @filename was in an invalid - * encoding. - * - * If you know the whole pathname of the file you should use - * g_filename_display_basename(), since that allows location-based - * translation of filenames. - * - * Returns: a newly allocated string containing - * a rendition of the filename in valid UTF-8 - * Since: 2.6 - */ - - -/** - * g_filename_from_uri: - * @uri: a uri describing a filename (escaped, encoded in ASCII). - * @hostname: (out) (optional) (nullable): Location to store hostname for the URI. - * If there is no hostname in the URI, %NULL will be - * stored in this location. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError may occur. - * - * Converts an escaped ASCII-encoded URI to a local filename in the - * encoding used for filenames. - * - * Returns: (type filename): a newly-allocated string holding - * the resulting filename, or %NULL on an error. - */ - - -/** - * g_filename_from_utf8: - * @utf8string: (type utf8): a UTF-8 encoded string. - * @len: the length of the string, or -1 if the string is - * nul-terminated. - * @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 UTF-8 to the encoding GLib uses for - * filenames. Note that on Windows GLib uses UTF-8 for filenames; - * on other platforms, this function indirectly depends on the - * [current locale][setlocale]. - * - * The input string shall not contain nul characters even if the @len - * argument is positive. A nul character found inside the string will result - * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the filename encoding is - * not UTF-8 and the conversion output contains a nul character, the error - * %G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL. - * - * Returns: (type filename): - * The converted string, or %NULL on an error. - */ - - -/** - * g_filename_to_uri: - * @filename: (type filename): an absolute filename specified in the GLib file - * name encoding, which is the on-disk file name bytes on Unix, and UTF-8 - * on Windows - * @hostname: (nullable): A UTF-8 encoded hostname, or %NULL for none. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError may occur. - * - * Converts an absolute filename to an escaped ASCII-encoded URI, with the path - * component following Section 3.3. of RFC 2396. - * - * Returns: a newly-allocated string holding the resulting - * URI, or %NULL on an error. - */ - - -/** - * g_filename_to_utf8: - * @opsysstring: (type filename): a string in the encoding for filenames - * @len: the length of the string, 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) - * @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 which is in the encoding used by GLib for - * filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8 - * for filenames; on other platforms, this function indirectly depends on - * the [current locale][setlocale]. - * - * The input string shall not contain nul characters even if the @len - * argument is positive. A nul character found inside the string will result - * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. - * If the source encoding is not UTF-8 and the conversion output contains a - * nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the - * function returns %NULL. Use g_convert() to produce output that - * may contain embedded nul characters. - * - * Returns: (type utf8): The converted string, or %NULL on an error. - */ - - -/** - * g_find_program_in_path: - * @program: (type filename): a program name in the GLib file name encoding - * - * Locates the first executable named @program in the user's path, in the - * same way that execvp() would locate it. Returns an allocated string - * with the absolute path name, or %NULL if the program is not found in - * the path. If @program is already an absolute path, returns a copy of - * @program if @program exists and is executable, and %NULL otherwise. - * - * On Windows, if @program does not have a file type suffix, tries - * with the suffixes .exe, .cmd, .bat and .com, and the suffixes in - * the `PATHEXT` environment variable. - * - * On Windows, it looks for the file in the same way as CreateProcess() - * would. This means first in the directory where the executing - * program was loaded from, then in the current directory, then in the - * Windows 32-bit system directory, then in the Windows directory, and - * finally in the directories in the `PATH` environment variable. If - * the program is found, the return value contains the full name - * including the type suffix. - * - * Returns: (type filename) (transfer full) (nullable): a newly-allocated - * string with the absolute path, or %NULL - */ - - -/** - * g_fopen: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * @mode: a string describing the mode in which the file should be opened - * - * A wrapper for the stdio `fopen()` function. The `fopen()` function - * opens a file and associates a new stream with it. - * - * Because file descriptors are specific to the C library on Windows, - * and a file descriptor is part of the `FILE` struct, the `FILE*` 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* returned by this function cannot be passed to C library - * functions like `fprintf()` or `fread()`. - * - * See your C library manual for more details about `fopen()`. - * - * As `close()` and `fclose()` are part of the C library, this implies that it is - * currently impossible to close a file if the application C library and the C library - * used by GLib are different. Convenience functions like g_file_set_contents_full() - * avoid this problem. - * - * Returns: A `FILE*` if the file was successfully opened, or %NULL if - * an error occurred - * Since: 2.6 - */ - - -/** - * g_format_size: - * @size: a size in bytes - * - * Formats a size (for example the size of a file) into a human readable - * string. Sizes are rounded to the nearest size prefix (kB, MB, GB) - * and are displayed rounded to the nearest tenth. E.g. the file size - * 3292528 bytes will be converted into the string "3.2 MB". The returned string - * is UTF-8, and may use a non-breaking space to separate the number and units, - * to ensure they aren’t separated when line wrapped. - * - * The prefix units base is 1000 (i.e. 1 kB is 1000 bytes). - * - * This string should be freed with g_free() when not needed any longer. - * - * See g_format_size_full() for more options about how the size might be - * formatted. - * - * Returns: (transfer full): a newly-allocated formatted string containing - * a human readable file size - * Since: 2.30 - */ - - -/** - * g_format_size_for_display: - * @size: a size in bytes - * - * Formats a size (for example the size of a file) into a human - * readable string. Sizes are rounded to the nearest size prefix - * (KB, MB, GB) and are displayed rounded to the nearest tenth. - * E.g. the file size 3292528 bytes will be converted into the - * string "3.1 MB". - * - * The prefix units base is 1024 (i.e. 1 KB is 1024 bytes). - * - * This string should be freed with g_free() when not needed any longer. - * - * Returns: (transfer full): a newly-allocated formatted string - * containing a human readable file size - * Since: 2.16 - * Deprecated: 2.30: This function is broken due to its use of SI - * suffixes to denote IEC units. Use g_format_size() instead. - */ - - -/** - * g_format_size_full: - * @size: a size in bytes - * @flags: #GFormatSizeFlags to modify the output - * - * Formats a size. - * - * This function is similar to g_format_size() but allows for flags - * that modify the output. See #GFormatSizeFlags. - * - * Returns: (transfer full): a newly-allocated formatted string - * containing a human readable file size - * Since: 2.30 - */ - - -/** - * g_fprintf: - * @file: (not nullable): the stream to write to. - * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] - * @...: the arguments to insert in the output. - * - * An implementation of the standard fprintf() function which supports - * positional parameters, as specified in the Single Unix Specification. - * - * `glib/gprintf.h` must be explicitly included in order to use this function. - * - * Returns: the number of bytes printed. - * Since: 2.2 - */ - - -/** - * g_free: - * @mem: (nullable): the memory to free - * - * Frees the memory pointed to by @mem. - * - * If @mem is %NULL it simply returns, so there is no need to check @mem - * against %NULL before calling this function. - */ - - -/** - * g_freopen: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * @mode: a string describing the mode in which the file should be opened - * @stream: (nullable): an existing stream which will be reused, or %NULL - * - * A wrapper for the POSIX freopen() function. The freopen() function - * opens a file and associates it with an existing stream. - * - * See your C library manual for more details about freopen(). - * - * Returns: A FILE* if the file was successfully opened, or %NULL if - * an error occurred. - * Since: 2.6 - */ - - -/** - * g_fsync: - * @fd: a file descriptor - * - * A wrapper for the POSIX `fsync()` function. On Windows, `_commit()` will be - * used. On macOS, `fcntl(F_FULLFSYNC)` will be used. - * The `fsync()` function is used to synchronize a file's in-core - * state with that of the disk. - * - * This wrapper will handle retrying on `EINTR`. - * - * See the C library manual for more details about fsync(). - * - * Returns: 0 on success, or -1 if an error occurred. - * The return value can be used exactly like the return value from fsync(). - * Since: 2.64 - */ - - -/** - * g_get_application_name: - * - * Gets a human-readable name for the application, as set by - * g_set_application_name(). This name should be localized if - * possible, and is intended for display to the user. Contrast with - * g_get_prgname(), which gets a non-localized name. If - * g_set_application_name() has not been called, returns the result of - * g_get_prgname() (which may be %NULL if g_set_prgname() has also not - * been called). - * - * Returns: (transfer none) (nullable): human-readable application - * name. May return %NULL - * Since: 2.2 - */ - - -/** - * g_get_charset: - * @charset: (out) (optional) (transfer none): return location for character set - * name, or %NULL. - * - * Obtains the character set for the [current locale][setlocale]; you - * might use this character set as an argument to g_convert(), to convert - * from the current locale's encoding to some other encoding. (Frequently - * g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.) - * - * On Windows the character set returned by this function is the - * so-called system default ANSI code-page. That is the character set - * used by the "narrow" versions of C library and Win32 functions that - * handle file names. It might be different from the character set - * used by the C library's current locale. - * - * On Linux, the character set is found by consulting nl_langinfo() if - * available. If not, the environment variables `LC_ALL`, `LC_CTYPE`, `LANG` - * and `CHARSET` are queried in order. - * - * The return value is %TRUE if the locale's encoding is UTF-8, in that - * case you can perhaps avoid calling g_convert(). - * - * The string returned in @charset is not allocated, and should not be - * freed. - * - * Returns: %TRUE if the returned charset is UTF-8 - */ - - -/** - * g_get_codeset: - * - * Gets the character set for the current locale. - * - * Returns: a newly allocated string containing the name - * of the character set. This string must be freed with g_free(). - */ - - -/** - * g_get_console_charset: - * @charset: (out) (optional) (transfer none): return location for character set - * name, or %NULL. - * - * Obtains the character set used by the console attached to the process, - * which is suitable for printing output to the terminal. - * - * Usually this matches the result returned by g_get_charset(), but in - * environments where the locale's character set does not match the encoding - * of the console this function tries to guess a more suitable value instead. - * - * On Windows the character set returned by this function is the - * output code page used by the console associated with the calling process. - * If the codepage can't be determined (for example because there is no - * console attached) UTF-8 is assumed. - * - * The return value is %TRUE if the locale's encoding is UTF-8, in that - * case you can perhaps avoid calling g_convert(). - * - * The string returned in @charset is not allocated, and should not be - * freed. - * - * Returns: %TRUE if the returned charset is UTF-8 - * Since: 2.62 - */ - - -/** - * g_get_current_dir: - * - * Gets the current directory. - * - * The returned string should be freed when no longer needed. - * The encoding of the returned string is system defined. - * On Windows, it is always UTF-8. - * - * Since GLib 2.40, this function will return the value of the "PWD" - * environment variable if it is set and it happens to be the same as - * the current directory. This can make a difference in the case that - * the current directory is the target of a symbolic link. - * - * Returns: (type filename): the current directory - */ - - -/** - * g_get_current_time: - * @result: #GTimeVal structure in which to store current time. - * - * Equivalent to the UNIX gettimeofday() function, but portable. - * - * You may find g_get_real_time() to be more convenient. - * - * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use g_get_real_time() - * instead. - */ - - -/** - * g_get_environ: - * - * Gets the list of environment variables for the current process. - * - * The list is %NULL terminated and each item in the list is of the - * form 'NAME=VALUE'. - * - * This is equivalent to direct access to the 'environ' global variable, - * except portable. - * - * The return value is freshly allocated and it should be freed with - * g_strfreev() when it is no longer needed. - * - * Returns: (array zero-terminated=1) (element-type filename) (transfer full): - * the list of environment variables - * Since: 2.28 - */ - - -/** - * g_get_filename_charsets: - * @filename_charsets: (out) (transfer none) (array zero-terminated=1): - * return location for the %NULL-terminated list of encoding names - * - * Determines the preferred character sets used for filenames. - * The first character set from the @charsets is the filename encoding, the - * subsequent character sets are used when trying to generate a displayable - * representation of a filename, see g_filename_display_name(). - * - * On Unix, the character sets are determined by consulting the - * environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`. - * On Windows, the character set used in the GLib API is always UTF-8 - * and said environment variables have no effect. - * - * `G_FILENAME_ENCODING` may be set to a comma-separated list of - * character set names. The special token "\@locale" is taken - * to mean the character set for the [current locale][setlocale]. - * If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is, - * the character set of the current locale is taken as the filename - * encoding. If neither environment variable is set, UTF-8 is taken - * as the filename encoding, but the character set of the current locale - * is also put in the list of encodings. - * - * The returned @charsets belong to GLib and must not be freed. - * - * Note that on Unix, regardless of the locale character set or - * `G_FILENAME_ENCODING` value, the actual file names present - * on a system might be in any random encoding or just gibberish. - * - * Returns: %TRUE if the filename encoding is UTF-8. - * Since: 2.6 - */ - - -/** - * g_get_home_dir: - * - * Gets the current user's home directory. - * - * As with most UNIX tools, this function will return the value of the - * `HOME` environment variable if it is set to an existing absolute path - * name, falling back to the `passwd` file in the case that it is unset. - * - * If the path given in `HOME` is non-absolute, does not exist, or is - * not a directory, the result is undefined. - * - * Before version 2.36 this function would ignore the `HOME` environment - * variable, taking the value from the `passwd` database instead. This was - * changed to increase the compatibility of GLib with other programs (and - * the XDG basedir specification) and to increase testability of programs - * based on GLib (by making it easier to run them from test frameworks). - * - * If your program has a strong requirement for either the new or the - * old behaviour (and if you don't wish to increase your GLib - * dependency to ensure that the new behaviour is in effect) then you - * should either directly check the `HOME` environment variable yourself - * or unset it before calling any functions in GLib. - * - * Returns: (type filename) (transfer none): the current user's home directory - */ - - -/** - * g_get_host_name: - * - * Return a name for the machine. - * - * The returned name is not necessarily a fully-qualified domain name, - * or even present in DNS or some other name service at all. It need - * not even be unique on your local network or site, but usually it - * is. Callers should not rely on the return value having any specific - * properties like uniqueness for security purposes. Even if the name - * of the machine is changed while an application is running, the - * return value from this function does not change. The returned - * string is owned by GLib and should not be modified or freed. If no - * name can be determined, a default fixed string "localhost" is - * returned. - * - * The encoding of the returned string is UTF-8. - * - * Returns: (transfer none): the host name of the machine. - * Since: 2.8 - */ - - -/** - * g_get_language_names: - * - * Computes a list of applicable locale names, which can be used to - * e.g. construct locale-dependent filenames or search paths. The returned - * list is sorted from most desirable to least desirable and always contains - * the default locale "C". - * - * For example, if LANGUAGE=de:en_US, then the returned list is - * "de", "en_US", "en", "C". - * - * This function consults the environment variables `LANGUAGE`, `LC_ALL`, - * `LC_MESSAGES` and `LANG` to find the list of locales specified by the - * user. - * - * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib - * that must not be modified or freed. - * Since: 2.6 - */ - - -/** - * g_get_language_names_with_category: - * @category_name: a locale category name - * - * Computes a list of applicable locale names with a locale category name, - * which can be used to construct the fallback locale-dependent filenames - * or search paths. The returned list is sorted from most desirable to - * least desirable and always contains the default locale "C". - * - * This function consults the environment variables `LANGUAGE`, `LC_ALL`, - * @category_name, and `LANG` to find the list of locales specified by the - * user. - * - * g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES"). - * - * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by - * the thread g_get_language_names_with_category was called from. - * It must not be modified or freed. It must be copied if planned to be used in another thread. - * Since: 2.58 - */ - - -/** - * g_get_locale_variants: - * @locale: a locale identifier - * - * Returns a list of derived variants of @locale, which can be used to - * e.g. construct locale-dependent filenames or search paths. The returned - * list is sorted from most desirable to least desirable. - * This function handles territory, charset and extra locale modifiers. See - * [`setlocale(3)`](man:setlocale) for information about locales and their format. - * - * @locale itself is guaranteed to be returned in the output. - * - * For example, if @locale is `fr_BE`, then the returned list - * is `fr_BE`, `fr`. If @locale is `en_GB.UTF-8@euro`, then the returned list - * is `en_GB.UTF-8@euro`, `en_GB.UTF-8`, `en_GB@euro`, `en_GB`, `en.UTF-8@euro`, - * `en.UTF-8`, `en@euro`, `en`. - * - * If you need the list of variants for the current locale, - * use g_get_language_names(). - * - * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly - * allocated array of newly allocated strings with the locale variants. Free with - * g_strfreev(). - * Since: 2.28 - */ - - -/** - * g_get_monotonic_time: - * - * Queries the system monotonic time. - * - * The monotonic clock will always increase and doesn't suffer - * discontinuities when the user (or NTP) changes the system time. It - * may or may not continue to tick during times where the machine is - * suspended. - * - * We try to use the clock that corresponds as closely as possible to - * the passage of time as measured by system calls such as poll() but it - * may not always be possible to do this. - * - * Returns: the monotonic time, in microseconds - * Since: 2.28 - */ - - -/** - * g_get_num_processors: - * - * Determine the approximate number of threads that the system will - * schedule simultaneously for this process. This is intended to be - * used as a parameter to g_thread_pool_new() for CPU bound tasks and - * similar cases. - * - * Returns: Number of schedulable threads, always greater than 0 - * Since: 2.36 - */ - - -/** - * g_get_os_info: - * @key_name: a key for the OS info being requested, for example %G_OS_INFO_KEY_NAME. - * - * Get information about the operating system. - * - * On Linux this comes from the `/etc/os-release` file. On other systems, it may - * come from a variety of sources. You can either use the standard key names - * like %G_OS_INFO_KEY_NAME or pass any UTF-8 string key name. For example, - * `/etc/os-release` provides a number of other less commonly used values that may - * be useful. No key is guaranteed to be provided, so the caller should always - * check if the result is %NULL. - * - * Returns: (nullable): The associated value for the requested key or %NULL if - * this information is not provided. - * Since: 2.64 - */ - - -/** - * g_get_prgname: - * - * Gets the name of the program. This name should not be localized, - * in contrast to g_get_application_name(). - * - * If you are using #GApplication the program name is set in - * g_application_run(). In case of GDK or GTK+ it is set in - * gdk_init(), which is called by gtk_init() and the - * #GtkApplication::startup handler. The program name is found by - * taking the last component of @argv[0]. - * - * Returns: (nullable) (transfer none): the name of the program, - * or %NULL if it has not been set yet. The returned string belongs - * to GLib and must not be modified or freed. - */ - - -/** - * g_get_real_name: - * - * Gets the real name of the user. This usually comes from the user's - * entry in the `passwd` file. The encoding of the returned string is - * system-defined. (On Windows, it is, however, always UTF-8.) If the - * real user name cannot be determined, the string "Unknown" is - * returned. - * - * Returns: (type filename) (transfer none): the user's real name. - */ - - -/** - * g_get_real_time: - * - * Queries the system wall-clock time. - * - * This call is functionally equivalent to g_get_current_time() except - * that the return value is often more convenient than dealing with a - * #GTimeVal. - * - * You should only use this call if you are actually interested in the real - * wall-clock time. g_get_monotonic_time() is probably more useful for - * measuring intervals. - * - * Returns: the number of microseconds since January 1, 1970 UTC. - * Since: 2.28 - */ - - -/** - * g_get_system_config_dirs: - * - * Returns an ordered list of base directories in which to access - * system-wide configuration information. - * - * On UNIX platforms this is determined using the mechanisms described - * in the - * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). - * In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`. - * - * On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_DIRS` is defined. - * If `XDG_CONFIG_DIRS` is undefined, the directory that contains application - * data for all users is used instead. A typical path is - * `C:\Documents and Settings\All Users\Application Data`. - * This folder is used for application data - * that is not user specific. For example, an application can store - * a spell-check dictionary, a database of clip art, or a log file in the - * FOLDERID_ProgramData folder. This information will not roam and is available - * to anyone using the computer. - * - * The return value is cached and modifying it at runtime is not supported, as - * it’s not thread-safe to modify environment variables at runtime. - * - * Returns: (array zero-terminated=1) (element-type filename) (transfer none): - * a %NULL-terminated array of strings owned by GLib that must not be - * modified or freed. - * Since: 2.6 - */ - - -/** - * g_get_system_data_dirs: - * - * Returns an ordered list of base directories in which to access - * system-wide application data. - * - * On UNIX platforms this is determined using the mechanisms described - * in the - * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec) - * In this case the list of directories retrieved will be `XDG_DATA_DIRS`. - * - * On Windows it follows XDG Base Directory Specification if `XDG_DATA_DIRS` is defined. - * If `XDG_DATA_DIRS` is undefined, - * the first elements in the list are the Application Data - * and Documents folders for All Users. (These can be determined only - * on Windows 2000 or later and are not present in the list on other - * Windows versions.) See documentation for FOLDERID_ProgramData and - * FOLDERID_PublicDocuments. - * - * Then follows the "share" subfolder in the installation folder for - * the package containing the DLL that calls this function, if it can - * be determined. - * - * Finally the list contains the "share" subfolder in the installation - * folder for GLib, and in the installation folder for the package the - * application's .exe file belongs to. - * - * The installation folders above are determined by looking up the - * folder where the module (DLL or EXE) in question is located. If the - * folder's name is "bin", its parent is used, otherwise the folder - * itself. - * - * Note that on Windows the returned list can vary depending on where - * this function is called. - * - * The return value is cached and modifying it at runtime is not supported, as - * it’s not thread-safe to modify environment variables at runtime. - * - * Returns: (array zero-terminated=1) (element-type filename) (transfer none): - * a %NULL-terminated array of strings owned by GLib that must not be - * modified or freed. - * Since: 2.6 - */ - - -/** - * g_get_tmp_dir: - * - * Gets the directory to use for temporary files. - * - * On UNIX, this is taken from the `TMPDIR` environment variable. - * If the variable is not set, `P_tmpdir` is - * used, as defined by the system C library. Failing that, a - * hard-coded default of "/tmp" is returned. - * - * On Windows, the `TEMP` environment variable is used, with the - * root directory of the Windows installation (eg: "C:\") used - * as a default. - * - * The encoding of the returned string is system-defined. On Windows, - * it is always UTF-8. The return value is never %NULL or the empty - * string. - * - * Returns: (type filename) (transfer none): the directory to use for temporary files. - */ - - -/** - * g_get_user_cache_dir: - * - * Returns a base directory in which to store non-essential, cached - * data specific to particular user. - * - * On UNIX platforms this is determined using the mechanisms described - * in the - * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). - * In this case the directory retrieved will be `XDG_CACHE_HOME`. - * - * On Windows it follows XDG Base Directory Specification if `XDG_CACHE_HOME` is defined. - * If `XDG_CACHE_HOME` is undefined, the directory that serves as a common - * repository for temporary Internet files is used instead. A typical path is - * `C:\Documents and Settings\username\Local Settings\Temporary Internet Files`. - * See the [documentation for `FOLDERID_InternetCache`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). - * - * The return value is cached and modifying it at runtime is not supported, as - * it’s not thread-safe to modify environment variables at runtime. - * - * Returns: (type filename) (transfer none): a string owned by GLib that - * must not be modified or freed. - * Since: 2.6 - */ - - -/** - * g_get_user_config_dir: - * - * Returns a base directory in which to store user-specific application - * configuration information such as user preferences and settings. - * - * On UNIX platforms this is determined using the mechanisms described - * in the - * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). - * In this case the directory retrieved will be `XDG_CONFIG_HOME`. - * - * On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_HOME` is defined. - * If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed - * to roaming) application data is used instead. See the - * [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). - * Note that in this case on Windows it will be the same - * as what g_get_user_data_dir() returns. - * - * The return value is cached and modifying it at runtime is not supported, as - * it’s not thread-safe to modify environment variables at runtime. - * - * Returns: (type filename) (transfer none): a string owned by GLib that - * must not be modified or freed. - * Since: 2.6 - */ - - -/** - * g_get_user_data_dir: - * - * Returns a base directory in which to access application data such - * as icons that is customized for a particular user. - * - * On UNIX platforms this is determined using the mechanisms described - * in the - * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). - * In this case the directory retrieved will be `XDG_DATA_HOME`. - * - * On Windows it follows XDG Base Directory Specification if `XDG_DATA_HOME` - * is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as - * opposed to roaming) application data is used instead. See the - * [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). - * Note that in this case on Windows it will be the same - * as what g_get_user_config_dir() returns. - * - * The return value is cached and modifying it at runtime is not supported, as - * it’s not thread-safe to modify environment variables at runtime. - * - * Returns: (type filename) (transfer none): a string owned by GLib that must - * not be modified or freed. - * Since: 2.6 - */ - - -/** - * g_get_user_name: - * - * Gets the user name of the current user. The encoding of the returned - * string is system-defined. On UNIX, it might be the preferred file name - * encoding, or something else, and there is no guarantee that it is even - * consistent on a machine. On Windows, it is always UTF-8. - * - * Returns: (type filename) (transfer none): the user name of the current user. - */ - - -/** - * g_get_user_runtime_dir: - * - * Returns a directory that is unique to the current user on the local - * system. - * - * This is determined using the mechanisms described - * in the - * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec). - * This is the directory - * specified in the `XDG_RUNTIME_DIR` environment variable. - * In the case that this variable is not set, we return the value of - * g_get_user_cache_dir(), after verifying that it exists. - * - * The return value is cached and modifying it at runtime is not supported, as - * it’s not thread-safe to modify environment variables at runtime. - * - * Returns: (type filename): a string owned by GLib that must not be - * modified or freed. - * Since: 2.28 - */ - - -/** - * g_get_user_special_dir: - * @directory: the logical id of special directory - * - * Returns the full path of a special directory using its logical id. - * - * On UNIX this is done using the XDG special user directories. - * For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP - * falls back to `$HOME/Desktop` when XDG special user directories have - * not been set up. - * - * Depending on the platform, the user might be able to change the path - * of the special directory without requiring the session to restart; GLib - * will not reflect any change once the special directories are loaded. - * - * Returns: (type filename): the path to the specified special directory, or - * %NULL if the logical id was not found. The returned string is owned by - * GLib and should not be modified or freed. - * Since: 2.14 - */ - - -/** - * g_getenv: - * @variable: (type filename): the environment variable to get - * - * Returns the value of an environment variable. - * - * On UNIX, the name and value are byte strings which might or might not - * be in some consistent character set and encoding. On Windows, they are - * in UTF-8. - * On Windows, in case the environment variable's value contains - * references to other environment variables, they are expanded. - * - * Returns: (type filename): the value of the environment variable, or %NULL if - * the environment variable is not found. The returned string - * may be overwritten by the next call to g_getenv(), g_setenv() - * or g_unsetenv(). - */ - - -/** - * g_hash_table_add: - * @hash_table: a #GHashTable - * @key: (transfer full): a key to insert - * - * This is a convenience function for using a #GHashTable as a set. It - * is equivalent to calling g_hash_table_replace() with @key as both the - * key and the value. - * - * In particular, this means that if @key already exists in the hash table, then - * the old copy of @key in the hash table is freed and @key replaces it in the - * table. - * - * When a hash table only ever contains keys that have themselves as the - * corresponding value it is able to be stored more efficiently. See - * the discussion in the section description. - * - * Starting from GLib 2.40, this function returns a boolean value to - * indicate whether the newly added value was already in the hash table - * or not. - * - * Returns: %TRUE if the key did not exist yet - * Since: 2.32 - */ - - -/** - * g_hash_table_contains: - * @hash_table: a #GHashTable - * @key: a key to check - * - * Checks if @key is in @hash_table. - * - * Returns: %TRUE if @key is in @hash_table, %FALSE otherwise. - * Since: 2.32 - */ - - -/** - * g_hash_table_destroy: - * @hash_table: a #GHashTable - * - * Destroys all keys and values in the #GHashTable and decrements its - * reference count by 1. If keys and/or values are dynamically allocated, - * you should either free them first or create the #GHashTable with destroy - * notifiers using g_hash_table_new_full(). In the latter case the destroy - * functions you supplied will be called on all keys and values during the - * destruction phase. - */ - - -/** - * g_hash_table_find: - * @hash_table: a #GHashTable - * @predicate: function to test the key/value pairs for a certain property - * @user_data: user data to pass to the function - * - * Calls the given function for key/value pairs in the #GHashTable - * until @predicate returns %TRUE. The function is passed the key - * and value of each pair, and the given @user_data parameter. The - * hash table may not be modified while iterating over it (you can't - * add/remove items). - * - * Note, that hash tables are really only optimized for forward - * lookups, i.e. g_hash_table_lookup(). So code that frequently issues - * g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of - * once per every entry in a hash table) should probably be reworked - * to use additional or different data structures for reverse lookups - * (keep in mind that an O(n) find/foreach operation issued for all n - * values in a hash table ends up needing O(n*n) operations). - * - * Returns: (nullable): The value of the first key/value pair is returned, - * for which @predicate evaluates to %TRUE. If no pair with the - * requested property is found, %NULL is returned. - * Since: 2.4 - */ - - -/** - * g_hash_table_foreach: - * @hash_table: a #GHashTable - * @func: the function to call for each key/value pair - * @user_data: user data to pass to the function - * - * Calls the given function for each of the key/value pairs in the - * #GHashTable. The function is passed the key and value of each - * pair, and the given @user_data parameter. The hash table may not - * be modified while iterating over it (you can't add/remove - * items). To remove all items matching a predicate, use - * g_hash_table_foreach_remove(). - * - * The order in which g_hash_table_foreach() iterates over the keys/values in - * the hash table is not defined. - * - * See g_hash_table_find() for performance caveats for linear - * order searches in contrast to g_hash_table_lookup(). - */ - - -/** - * g_hash_table_foreach_remove: - * @hash_table: a #GHashTable - * @func: the function to call for each key/value pair - * @user_data: user data to pass to the function - * - * Calls the given function for each key/value pair in the - * #GHashTable. If the function returns %TRUE, then the key/value - * pair is removed from the #GHashTable. If you supplied key or - * value destroy functions when creating the #GHashTable, they are - * used to free the memory allocated for the removed keys and values. - * - * See #GHashTableIter for an alternative way to loop over the - * key/value pairs in the hash table. - * - * Returns: the number of key/value pairs removed - */ - - -/** - * g_hash_table_foreach_steal: - * @hash_table: a #GHashTable - * @func: the function to call for each key/value pair - * @user_data: user data to pass to the function - * - * Calls the given function for each key/value pair in the - * #GHashTable. If the function returns %TRUE, then the key/value - * pair is removed from the #GHashTable, but no key or value - * destroy functions are called. - * - * See #GHashTableIter for an alternative way to loop over the - * key/value pairs in the hash table. - * - * Returns: the number of key/value pairs removed. - */ - - -/** - * g_hash_table_freeze: - * @hash_table: a #GHashTable - * - * This function is deprecated and will be removed in the next major - * release of GLib. It does nothing. - */ - - -/** - * g_hash_table_get_keys: - * @hash_table: a #GHashTable - * - * Retrieves every key inside @hash_table. The returned data is valid - * until changes to the hash release those keys. - * - * This iterates over every entry in the hash table to build its return value. - * To iterate over the entries in a #GHashTable more efficiently, use a - * #GHashTableIter. - * - * Returns: (transfer container): a #GList containing all the keys - * inside the hash table. The content of the list is owned by the - * hash table and should not be modified or freed. Use g_list_free() - * when done using the list. - * Since: 2.14 - */ - - -/** - * g_hash_table_get_keys_as_array: - * @hash_table: a #GHashTable - * @length: (out) (optional): the length of the returned array - * - * Retrieves every key inside @hash_table, as an array. - * - * The returned array is %NULL-terminated but may contain %NULL as a - * key. Use @length to determine the true length if it's possible that - * %NULL was used as the value for a key. - * - * Note: in the common case of a string-keyed #GHashTable, the return - * value of this function can be conveniently cast to (const gchar **). - * - * This iterates over every entry in the hash table to build its return value. - * To iterate over the entries in a #GHashTable more efficiently, use a - * #GHashTableIter. - * - * You should always free the return result with g_free(). In the - * above-mentioned case of a string-keyed hash table, it may be - * appropriate to use g_strfreev() if you call g_hash_table_steal_all() - * first to transfer ownership of the keys. - * - * Returns: (array length=length) (transfer container): a - * %NULL-terminated array containing each key from the table. - * Since: 2.40 - */ - - -/** - * g_hash_table_get_values: - * @hash_table: a #GHashTable - * - * Retrieves every value inside @hash_table. The returned data - * is valid until @hash_table is modified. - * - * This iterates over every entry in the hash table to build its return value. - * To iterate over the entries in a #GHashTable more efficiently, use a - * #GHashTableIter. - * - * Returns: (transfer container): a #GList containing all the values - * inside the hash table. The content of the list is owned by the - * hash table and should not be modified or freed. Use g_list_free() - * when done using the list. - * Since: 2.14 - */ - - -/** - * g_hash_table_insert: - * @hash_table: a #GHashTable - * @key: a key to insert - * @value: the value to associate with the key - * - * Inserts a new key and value into a #GHashTable. - * - * If the key already exists in the #GHashTable its current - * value is replaced with the new value. If you supplied a - * @value_destroy_func when creating the #GHashTable, the old - * value is freed using that function. If you supplied a - * @key_destroy_func when creating the #GHashTable, the passed - * key is freed using that function. - * - * Starting from GLib 2.40, this function returns a boolean value to - * indicate whether the newly added value was already in the hash table - * or not. - * - * Returns: %TRUE if the key did not exist yet - */ - - -/** - * g_hash_table_iter_get_hash_table: - * @iter: an initialized #GHashTableIter - * - * Returns the #GHashTable associated with @iter. - * - * Returns: the #GHashTable associated with @iter. - * Since: 2.16 - */ - - -/** - * g_hash_table_iter_init: - * @iter: an uninitialized #GHashTableIter - * @hash_table: a #GHashTable - * - * Initializes a key/value pair iterator and associates it with - * @hash_table. Modifying the hash table after calling this function - * invalidates the returned iterator. - * - * The iteration order of a #GHashTableIter over the keys/values in a hash - * table is not defined. - * - * |[<!-- language="C" --> - * GHashTableIter iter; - * gpointer key, value; - * - * g_hash_table_iter_init (&iter, hash_table); - * while (g_hash_table_iter_next (&iter, &key, &value)) - * { - * // do something with key and value - * } - * ]| - * - * Since: 2.16 - */ - - -/** - * g_hash_table_iter_next: - * @iter: an initialized #GHashTableIter - * @key: (out) (optional): a location to store the key - * @value: (out) (optional) (nullable): a location to store the value - * - * Advances @iter and retrieves the key and/or value that are now - * pointed to as a result of this advancement. If %FALSE is returned, - * @key and @value are not set, and the iterator becomes invalid. - * - * Returns: %FALSE if the end of the #GHashTable has been reached. - * Since: 2.16 - */ - - -/** - * g_hash_table_iter_remove: - * @iter: an initialized #GHashTableIter - * - * Removes the key/value pair currently pointed to by the iterator - * from its associated #GHashTable. Can only be called after - * g_hash_table_iter_next() returned %TRUE, and cannot be called - * more than once for the same key/value pair. - * - * If the #GHashTable was created using g_hash_table_new_full(), - * the key and value are freed using the supplied destroy functions, - * otherwise you have to make sure that any dynamically allocated - * values are freed yourself. - * - * It is safe to continue iterating the #GHashTable afterward: - * |[<!-- language="C" --> - * while (g_hash_table_iter_next (&iter, &key, &value)) - * { - * if (condition) - * g_hash_table_iter_remove (&iter); - * } - * ]| - * - * Since: 2.16 - */ - - -/** - * g_hash_table_iter_replace: - * @iter: an initialized #GHashTableIter - * @value: the value to replace with - * - * Replaces the value currently pointed to by the iterator - * from its associated #GHashTable. Can only be called after - * g_hash_table_iter_next() returned %TRUE. - * - * If you supplied a @value_destroy_func when creating the - * #GHashTable, the old value is freed using that function. - * - * Since: 2.30 - */ - - -/** - * g_hash_table_iter_steal: - * @iter: an initialized #GHashTableIter - * - * Removes the key/value pair currently pointed to by the - * iterator from its associated #GHashTable, without calling - * the key and value destroy functions. Can only be called - * after g_hash_table_iter_next() returned %TRUE, and cannot - * be called more than once for the same key/value pair. - * - * Since: 2.16 - */ - - -/** - * g_hash_table_lookup: - * @hash_table: a #GHashTable - * @key: the key to look up - * - * Looks up a key in a #GHashTable. Note that this function cannot - * distinguish between a key that is not present and one which is present - * and has the value %NULL. If you need this distinction, use - * g_hash_table_lookup_extended(). - * - * Returns: (nullable): the associated value, or %NULL if the key is not found - */ - - -/** - * g_hash_table_lookup_extended: - * @hash_table: a #GHashTable - * @lookup_key: the key to look up - * @orig_key: (out) (optional): return location for the original key - * @value: (out) (optional) (nullable): return location for the value associated - * with the key - * - * Looks up a key in the #GHashTable, returning the original key and the - * associated value and a #gboolean which is %TRUE if the key was found. This - * is useful if you need to free the memory allocated for the original key, - * for example before calling g_hash_table_remove(). - * - * You can actually pass %NULL for @lookup_key to test - * whether the %NULL key exists, provided the hash and equal functions - * of @hash_table are %NULL-safe. - * - * Returns: %TRUE if the key was found in the #GHashTable - */ - - -/** - * g_hash_table_new: - * @hash_func: a function to create a hash value from a key - * @key_equal_func: a function to check two keys for equality - * - * Creates a new #GHashTable with a reference count of 1. - * - * Hash values returned by @hash_func are used to determine where keys - * are stored within the #GHashTable data structure. The g_direct_hash(), - * g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash() - * functions are provided for some common types of keys. - * If @hash_func is %NULL, g_direct_hash() is used. - * - * @key_equal_func is used when looking up keys in the #GHashTable. - * The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal() - * and g_str_equal() functions are provided for the most common types - * of keys. If @key_equal_func is %NULL, keys are compared directly in - * a similar fashion to g_direct_equal(), but without the overhead of - * a function call. @key_equal_func is called with the key from the hash table - * as its first parameter, and the user-provided key to check against as - * its second. - * - * Returns: a new #GHashTable - */ - - -/** - * g_hash_table_new_full: - * @hash_func: a function to create a hash value from a key - * @key_equal_func: a function to check two keys for equality - * @key_destroy_func: (nullable): a function to free the memory allocated for the key - * used when removing the entry from the #GHashTable, or %NULL - * if you don't want to supply such a function. - * @value_destroy_func: (nullable): a function to free the memory allocated for the - * value used when removing the entry from the #GHashTable, or %NULL - * if you don't want to supply such a function. - * - * Creates a new #GHashTable like g_hash_table_new() with a reference - * count of 1 and allows to specify functions to free the memory - * allocated for the key and value that get called when removing the - * entry from the #GHashTable. - * - * Since version 2.42 it is permissible for destroy notify functions to - * recursively remove further items from the hash table. This is only - * permissible if the application still holds a reference to the hash table. - * This means that you may need to ensure that the hash table is empty by - * calling g_hash_table_remove_all() before releasing the last reference using - * g_hash_table_unref(). - * - * Returns: a new #GHashTable - */ - - -/** - * g_hash_table_ref: - * @hash_table: a valid #GHashTable - * - * Atomically increments the reference count of @hash_table by one. - * This function is MT-safe and may be called from any thread. - * - * Returns: the passed in #GHashTable - * Since: 2.10 - */ - - -/** - * g_hash_table_remove: - * @hash_table: a #GHashTable - * @key: the key to remove - * - * Removes a key and its associated value from a #GHashTable. - * - * If the #GHashTable was created using g_hash_table_new_full(), the - * key and value are freed using the supplied destroy functions, otherwise - * you have to make sure that any dynamically allocated values are freed - * yourself. - * - * Returns: %TRUE if the key was found and removed from the #GHashTable - */ - - -/** - * g_hash_table_remove_all: - * @hash_table: a #GHashTable - * - * Removes all keys and their associated values from a #GHashTable. - * - * If the #GHashTable was created using g_hash_table_new_full(), - * the keys and values are freed using the supplied destroy functions, - * otherwise you have to make sure that any dynamically allocated - * values are freed yourself. - * - * Since: 2.12 - */ - - -/** - * g_hash_table_replace: - * @hash_table: a #GHashTable - * @key: a key to insert - * @value: the value to associate with the key - * - * Inserts a new key and value into a #GHashTable similar to - * g_hash_table_insert(). The difference is that if the key - * already exists in the #GHashTable, it gets replaced by the - * new key. If you supplied a @value_destroy_func when creating - * the #GHashTable, the old value is freed using that function. - * If you supplied a @key_destroy_func when creating the - * #GHashTable, the old key is freed using that function. - * - * Starting from GLib 2.40, this function returns a boolean value to - * indicate whether the newly added value was already in the hash table - * or not. - * - * Returns: %TRUE if the key did not exist yet - */ - - -/** - * g_hash_table_size: - * @hash_table: a #GHashTable - * - * Returns the number of elements contained in the #GHashTable. - * - * Returns: the number of key/value pairs in the #GHashTable. - */ - - -/** - * g_hash_table_steal: - * @hash_table: a #GHashTable - * @key: the key to remove - * - * Removes a key and its associated value from a #GHashTable without - * calling the key and value destroy functions. - * - * Returns: %TRUE if the key was found and removed from the #GHashTable - */ - - -/** - * g_hash_table_steal_all: - * @hash_table: a #GHashTable - * - * Removes all keys and their associated values from a #GHashTable - * without calling the key and value destroy functions. - * - * Since: 2.12 - */ - - -/** - * g_hash_table_steal_extended: - * @hash_table: a #GHashTable - * @lookup_key: the key to look up - * @stolen_key: (out) (optional) (transfer full): return location for the - * original key - * @stolen_value: (out) (optional) (nullable) (transfer full): return location - * for the value associated with the key - * - * Looks up a key in the #GHashTable, stealing the original key and the - * associated value and returning %TRUE if the key was found. If the key was - * not found, %FALSE is returned. - * - * If found, the stolen key and value are removed from the hash table without - * calling the key and value destroy functions, and ownership is transferred to - * the caller of this method; as with g_hash_table_steal(). - * - * You can pass %NULL for @lookup_key, provided the hash and equal functions - * of @hash_table are %NULL-safe. - * - * Returns: %TRUE if the key was found in the #GHashTable - * Since: 2.58 - */ - - -/** - * g_hash_table_thaw: - * @hash_table: a #GHashTable - * - * This function is deprecated and will be removed in the next major - * release of GLib. It does nothing. - */ - - -/** - * g_hash_table_unref: - * @hash_table: a valid #GHashTable - * - * Atomically decrements the reference count of @hash_table by one. - * If the reference count drops to 0, all keys and values will be - * destroyed, and all memory allocated by the hash table is released. - * This function is MT-safe and may be called from any thread. - * - * Since: 2.10 - */ - - -/** - * g_hmac_copy: - * @hmac: the #GHmac to copy - * - * Copies a #GHmac. If @hmac has been closed, by calling - * g_hmac_get_string() or g_hmac_get_digest(), the copied - * HMAC will be closed as well. - * - * Returns: the copy of the passed #GHmac. Use g_hmac_unref() - * when finished using it. - * Since: 2.30 - */ - - -/** - * g_hmac_get_digest: - * @hmac: a #GHmac - * @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 array and places it - * into @buffer. The size of the digest depends on the type of checksum. - * - * Once this function has been called, the #GHmac is closed and can - * no longer be updated with g_checksum_update(). - * - * Since: 2.30 - */ - - -/** - * g_hmac_get_string: - * @hmac: a #GHmac - * - * Gets the HMAC as a hexadecimal string. - * - * Once this function has been called the #GHmac can no longer be - * updated with g_hmac_update(). - * - * The hexadecimal characters will be lower case. - * - * Returns: the hexadecimal representation of the HMAC. The - * returned string is owned by the HMAC and should not be modified - * or freed. - * Since: 2.30 - */ - - -/** - * g_hmac_new: - * @digest_type: the desired type of digest - * @key: (array length=key_len): the key for the HMAC - * @key_len: the length of the keys - * - * Creates a new #GHmac, using the digest algorithm @digest_type. - * If the @digest_type is not known, %NULL is returned. - * A #GHmac can be used to compute the HMAC of a key and an - * arbitrary binary blob, using different hashing algorithms. - * - * A #GHmac works by feeding a binary blob through g_hmac_update() - * until the data is complete; the digest can then be extracted - * using g_hmac_get_string(), which will return the checksum as a - * hexadecimal string; or g_hmac_get_digest(), which will return a - * array of raw bytes. Once either g_hmac_get_string() or - * g_hmac_get_digest() have been called on a #GHmac, the HMAC - * will be closed and it won't be possible to call g_hmac_update() - * on it anymore. - * - * Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42. - * Support for %G_CHECKSUM_SHA384 was added in GLib 2.52. - * - * Returns: the newly created #GHmac, or %NULL. - * Use g_hmac_unref() to free the memory allocated by it. - * Since: 2.30 - */ - - -/** - * g_hmac_ref: - * @hmac: a valid #GHmac - * - * Atomically increments the reference count of @hmac by one. - * - * This function is MT-safe and may be called from any thread. - * - * Returns: the passed in #GHmac. - * Since: 2.30 - */ - - -/** - * g_hmac_unref: - * @hmac: a #GHmac - * - * Atomically decrements the reference count of @hmac by one. - * - * If the reference count drops to 0, all keys and values will be - * destroyed, and all memory allocated by the hash table is released. - * This function is MT-safe and may be called from any thread. - * Frees the memory allocated for @hmac. - * - * Since: 2.30 - */ - - -/** - * g_hmac_update: - * @hmac: a #GHmac - * @data: (array length=length): buffer used to compute the checksum - * @length: size of the buffer, or -1 if it is a nul-terminated string - * - * Feeds @data into an existing #GHmac. - * - * The HMAC must still be open, that is g_hmac_get_string() or - * g_hmac_get_digest() must not have been called on @hmac. - * - * Since: 2.30 - */ - - -/** - * g_hook_alloc: - * @hook_list: a #GHookList - * - * Allocates space for a #GHook and initializes it. - * - * Returns: a new #GHook - */ - - -/** - * g_hook_append: - * @hook_list: a #GHookList - * @hook: the #GHook to add to the end of @hook_list - * - * Appends a #GHook onto the end of a #GHookList. - */ - - -/** - * g_hook_compare_ids: - * @new_hook: a #GHook - * @sibling: a #GHook to compare with @new_hook - * - * Compares the ids of two #GHook elements, returning a negative value - * if the second id is greater than the first. - * - * Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook - */ - - -/** - * g_hook_destroy: - * @hook_list: a #GHookList - * @hook_id: a hook ID - * - * Destroys a #GHook, given its ID. - * - * Returns: %TRUE if the #GHook was found in the #GHookList and destroyed - */ - - -/** - * g_hook_destroy_link: - * @hook_list: a #GHookList - * @hook: the #GHook to remove - * - * Removes one #GHook from a #GHookList, marking it - * inactive and calling g_hook_unref() on it. - */ - - -/** - * g_hook_find: - * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed - * should be skipped - * @func: the function to call for each #GHook, which should return - * %TRUE when the #GHook has been found - * @data: the data to pass to @func - * - * Finds a #GHook in a #GHookList using the given function to - * test for a match. - * - * Returns: the found #GHook or %NULL if no matching #GHook is found - */ - - -/** - * g_hook_find_data: - * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed - * should be skipped - * @data: the data to find - * - * Finds a #GHook in a #GHookList with the given data. - * - * Returns: the #GHook with the given @data or %NULL if no matching - * #GHook is found - */ - - -/** - * g_hook_find_func: - * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed - * should be skipped - * @func: the function to find - * - * Finds a #GHook in a #GHookList with the given function. - * - * Returns: the #GHook with the given @func or %NULL if no matching - * #GHook is found - */ - - -/** - * g_hook_find_func_data: - * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed - * should be skipped - * @func: (not nullable): the function to find - * @data: the data to find - * - * Finds a #GHook in a #GHookList with the given function and data. - * - * Returns: the #GHook with the given @func and @data or %NULL if - * no matching #GHook is found - */ - - -/** - * g_hook_first_valid: - * @hook_list: a #GHookList - * @may_be_in_call: %TRUE if hooks which are currently running - * (e.g. in another thread) are considered valid. If set to %FALSE, - * these are skipped - * - * Returns the first #GHook in a #GHookList which has not been destroyed. - * The reference count for the #GHook is incremented, so you must call - * g_hook_unref() to restore it when no longer needed. (Or call - * g_hook_next_valid() if you are stepping through the #GHookList.) - * - * Returns: the first valid #GHook, or %NULL if none are valid - */ - - -/** - * g_hook_free: - * @hook_list: a #GHookList - * @hook: the #GHook to free - * - * Calls the #GHookList @finalize_hook function if it exists, - * and frees the memory allocated for the #GHook. - */ - - -/** - * g_hook_get: - * @hook_list: a #GHookList - * @hook_id: a hook id - * - * Returns the #GHook with the given id, or %NULL if it is not found. - * - * Returns: the #GHook with the given id, or %NULL if it is not found - */ - - -/** - * g_hook_insert_before: - * @hook_list: a #GHookList - * @sibling: (nullable): the #GHook to insert the new #GHook before - * @hook: the #GHook to insert - * - * Inserts a #GHook into a #GHookList, before a given #GHook. - */ - - -/** - * g_hook_insert_sorted: - * @hook_list: a #GHookList - * @hook: the #GHook to insert - * @func: the comparison function used to sort the #GHook elements - * - * Inserts a #GHook into a #GHookList, sorted by the given function. - */ - - -/** - * g_hook_list_clear: - * @hook_list: a #GHookList - * - * Removes all the #GHook elements from a #GHookList. - */ - - -/** - * g_hook_list_init: - * @hook_list: a #GHookList - * @hook_size: the size of each element in the #GHookList, - * typically `sizeof (GHook)`. - * - * Initializes a #GHookList. - * This must be called before the #GHookList is used. - */ - - -/** - * g_hook_list_invoke: - * @hook_list: a #GHookList - * @may_recurse: %TRUE if functions which are already running - * (e.g. in another thread) can be called. If set to %FALSE, - * these are skipped - * - * Calls all of the #GHook functions in a #GHookList. - */ - - -/** - * g_hook_list_invoke_check: - * @hook_list: a #GHookList - * @may_recurse: %TRUE if functions which are already running - * (e.g. in another thread) can be called. If set to %FALSE, - * these are skipped - * - * Calls all of the #GHook functions in a #GHookList. - * Any function which returns %FALSE is removed from the #GHookList. - */ - - -/** - * g_hook_list_marshal: - * @hook_list: a #GHookList - * @may_recurse: %TRUE if hooks which are currently running - * (e.g. in another thread) are considered valid. If set to %FALSE, - * these are skipped - * @marshaller: the function to call for each #GHook - * @marshal_data: data to pass to @marshaller - * - * Calls a function on each valid #GHook. - */ - - -/** - * g_hook_list_marshal_check: - * @hook_list: a #GHookList - * @may_recurse: %TRUE if hooks which are currently running - * (e.g. in another thread) are considered valid. If set to %FALSE, - * these are skipped - * @marshaller: the function to call for each #GHook - * @marshal_data: data to pass to @marshaller - * - * Calls a function on each valid #GHook and destroys it if the - * function returns %FALSE. - */ - - -/** - * g_hook_next_valid: - * @hook_list: a #GHookList - * @hook: the current #GHook - * @may_be_in_call: %TRUE if hooks which are currently running - * (e.g. in another thread) are considered valid. If set to %FALSE, - * these are skipped - * - * Returns the next #GHook in a #GHookList which has not been destroyed. - * The reference count for the #GHook is incremented, so you must call - * g_hook_unref() to restore it when no longer needed. (Or continue to call - * g_hook_next_valid() until %NULL is returned.) - * - * Returns: the next valid #GHook, or %NULL if none are valid - */ - - -/** - * g_hook_prepend: - * @hook_list: a #GHookList - * @hook: the #GHook to add to the start of @hook_list - * - * Prepends a #GHook on the start of a #GHookList. - */ - - -/** - * g_hook_ref: - * @hook_list: a #GHookList - * @hook: the #GHook to increment the reference count of - * - * Increments the reference count for a #GHook. - * - * Returns: the @hook that was passed in (since 2.6) - */ - - -/** - * g_hook_unref: - * @hook_list: a #GHookList - * @hook: the #GHook to unref - * - * Decrements the reference count of a #GHook. - * If the reference count falls to 0, the #GHook is removed - * from the #GHookList and g_hook_free() is called to free it. - */ - - -/** - * g_hostname_is_ascii_encoded: - * @hostname: a hostname - * - * Tests if @hostname contains segments with an ASCII-compatible - * encoding of an Internationalized Domain Name. If this returns - * %TRUE, you should decode the hostname with g_hostname_to_unicode() - * before displaying it to the user. - * - * Note that a hostname might contain a mix of encoded and unencoded - * segments, and so it is possible for g_hostname_is_non_ascii() and - * g_hostname_is_ascii_encoded() to both return %TRUE for a name. - * - * Returns: %TRUE if @hostname contains any ASCII-encoded - * segments. - * Since: 2.22 - */ - - -/** - * g_hostname_is_ip_address: - * @hostname: a hostname (or IP address in string form) - * - * Tests if @hostname is the string form of an IPv4 or IPv6 address. - * (Eg, "192.168.0.1".) - * - * Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874). - * - * Returns: %TRUE if @hostname is an IP address - * Since: 2.22 - */ - - -/** - * g_hostname_is_non_ascii: - * @hostname: a hostname - * - * Tests if @hostname contains Unicode characters. If this returns - * %TRUE, you need to encode the hostname with g_hostname_to_ascii() - * before using it in non-IDN-aware contexts. - * - * Note that a hostname might contain a mix of encoded and unencoded - * segments, and so it is possible for g_hostname_is_non_ascii() and - * g_hostname_is_ascii_encoded() to both return %TRUE for a name. - * - * Returns: %TRUE if @hostname contains any non-ASCII characters - * Since: 2.22 - */ - - -/** - * g_hostname_to_ascii: - * @hostname: a valid UTF-8 or ASCII hostname - * - * Converts @hostname to its canonical ASCII form; an ASCII-only - * string containing no uppercase letters and not ending with a - * trailing dot. - * - * Returns: (nullable) (transfer full): an ASCII hostname, which must be freed, - * or %NULL if @hostname is in some way invalid. - * Since: 2.22 - */ - - -/** - * g_hostname_to_unicode: - * @hostname: a valid UTF-8 or ASCII hostname - * - * Converts @hostname to its canonical presentation form; a UTF-8 - * string in Unicode normalization form C, containing no uppercase - * letters, no forbidden characters, and no ASCII-encoded segments, - * and not ending with a trailing dot. - * - * Of course if @hostname is not an internationalized hostname, then - * the canonical presentation form will be entirely ASCII. - * - * Returns: (nullable) (transfer full): a UTF-8 hostname, which must be freed, - * or %NULL if @hostname is in some way invalid. - * Since: 2.22 - */ - - -/** - * g_htonl: - * @val: a 32-bit integer value in host byte order - * - * Converts a 32-bit integer value from host to network byte order. - * - * Returns: @val converted to network byte order - */ - - -/** - * g_htons: - * @val: a 16-bit integer value in host byte order - * - * Converts a 16-bit integer value from host to network byte order. - * - * Returns: @val converted to network byte order - */ - - -/** - * g_iconv: (skip) - * @converter: conversion descriptor from g_iconv_open() - * @inbuf: bytes to convert - * @inbytes_left: inout parameter, bytes remaining to convert in @inbuf - * @outbuf: converted output bytes - * @outbytes_left: inout parameter, bytes available to fill in @outbuf - * - * Same as the standard UNIX routine iconv(), but - * may be implemented via libiconv on UNIX flavors that lack - * a native implementation. - * - * GLib provides g_convert() and g_locale_to_utf8() which are likely - * more convenient than the raw iconv wrappers. - * - * Note that the behaviour of iconv() for characters which are valid in the - * input character set, but which have no representation in the output character - * set, is implementation defined. This function may return success (with a - * positive number of non-reversible conversions as replacement characters were - * used), or it may return -1 and set an error such as %EILSEQ, in such a - * situation. - * - * Returns: count of non-reversible conversions, or -1 on error - */ - - -/** - * g_iconv_close: (skip) - * @converter: a conversion descriptor from g_iconv_open() - * - * Same as the standard UNIX routine iconv_close(), but - * may be implemented via libiconv on UNIX flavors that lack - * a native implementation. Should be called to clean up - * the conversion descriptor from g_iconv_open() when - * you are done converting things. - * - * GLib provides g_convert() and g_locale_to_utf8() which are likely - * more convenient than the raw iconv wrappers. - * - * Returns: -1 on error, 0 on success - */ - - -/** - * g_iconv_open: (skip) - * @to_codeset: destination codeset - * @from_codeset: source codeset - * - * Same as the standard UNIX routine iconv_open(), but - * may be implemented via libiconv on UNIX flavors that lack - * a native implementation. - * - * GLib provides g_convert() and g_locale_to_utf8() which are likely - * more convenient than the raw iconv wrappers. - * - * Returns: a "conversion descriptor", or (GIConv)-1 if - * opening the converter failed. - */ - - -/** - * g_idle_add: - * @function: function to call - * @data: data to pass to @function. - * - * Adds a function to be called whenever there are no higher priority - * events pending to the default main loop. The function is given the - * default idle priority, %G_PRIORITY_DEFAULT_IDLE. If the function - * returns %FALSE it is automatically removed from the list of event - * sources and will not be called again. - * - * See [memory management of sources][mainloop-memory-management] for details - * on how to handle the return value and memory management of @data. - * - * This internally creates a main loop source using g_idle_source_new() - * and attaches it to the global #GMainContext using g_source_attach(), so - * the callback will be invoked in whichever thread is running that main - * context. You can do these steps manually if you need greater control or to - * use a custom main context. - * - * Returns: the ID (greater than 0) of the event source. - */ - - -/** - * g_idle_add_full: (rename-to g_idle_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. - * @function: function to call - * @data: data to pass to @function - * @notify: (nullable): function to call when the idle is removed, or %NULL - * - * Adds a function to be called whenever there are no higher priority - * events pending. - * - * If the function returns %G_SOURCE_REMOVE or %FALSE it is automatically - * removed from the list of event sources and will not be called again. - * - * See [memory management of sources][mainloop-memory-management] for details - * on how to handle the return value and memory management of @data. - * - * This internally creates a main loop source using g_idle_source_new() - * and attaches it to the global #GMainContext using g_source_attach(), so - * the callback will be invoked in whichever thread is running that main - * context. You can do these steps manually if you need greater control or to - * use a custom main context. - * - * Returns: the ID (greater than 0) of the event source. - */ - - -/** - * g_idle_remove_by_data: - * @data: the data for the idle source's callback. - * - * Removes the idle function with the given data. - * - * Returns: %TRUE if an idle source was found and removed. - */ - - -/** - * g_idle_source_new: - * - * Creates a new idle 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 the default priority for idle sources is - * %G_PRIORITY_DEFAULT_IDLE, as compared to other sources which - * have a default priority of %G_PRIORITY_DEFAULT. - * - * Returns: the newly-created idle source - */ - - -/** - * g_info: - * @...: format string, followed by parameters to insert - * into the format string (as with printf()) - * - * A convenience function/macro to log an informational message. Seldom used. - * - * 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. - * - * Such messages are suppressed by the g_log_default_handler() and - * g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is - * set appropriately. - * - * If structured logging is enabled, this will use g_log_structured(); - * otherwise it will use g_log(). See - * [Using Structured Logging][using-structured-logging]. - * - * Since: 2.40 - */ - - -/** - * g_int64_equal: - * @v1: (not nullable): a pointer to a #gint64 key - * @v2: (not nullable): a pointer to a #gint64 key to compare with @v1 - * - * Compares the two #gint64 values being pointed to and returns - * %TRUE if they are equal. - * It can be passed to g_hash_table_new() as the @key_equal_func - * parameter, when using non-%NULL pointers to 64-bit integers as keys in a - * #GHashTable. - * - * Returns: %TRUE if the two keys match. - * Since: 2.22 - */ - - -/** - * g_int64_hash: - * @v: (not nullable): a pointer to a #gint64 key - * - * Converts a pointer to a #gint64 to a hash value. - * - * It can be passed to g_hash_table_new() as the @hash_func parameter, - * when using non-%NULL pointers to 64-bit integer values as keys in a - * #GHashTable. - * - * Returns: a hash value corresponding to the key. - * Since: 2.22 - */ - - -/** - * g_int_equal: - * @v1: (not nullable): a pointer to a #gint key - * @v2: (not nullable): a pointer to a #gint key to compare with @v1 - * - * Compares the two #gint values being pointed to and returns - * %TRUE if they are equal. - * It can be passed to g_hash_table_new() as the @key_equal_func - * parameter, when using non-%NULL pointers to integers as keys in a - * #GHashTable. - * - * Note that this function acts on pointers to #gint, not on #gint - * directly: if your hash table's keys are of the form - * `GINT_TO_POINTER (n)`, use g_direct_equal() instead. - * - * Returns: %TRUE if the two keys match. - */ - - -/** - * g_int_hash: - * @v: (not nullable): a pointer to a #gint key - * - * Converts a pointer to a #gint to a hash value. - * It can be passed to g_hash_table_new() as the @hash_func parameter, - * when using non-%NULL pointers to integer values as keys in a #GHashTable. - * - * Note that this function acts on pointers to #gint, not on #gint - * directly: if your hash table's keys are of the form - * `GINT_TO_POINTER (n)`, use g_direct_hash() instead. - * - * Returns: a hash value corresponding to the key. - */ - - -/** - * g_intern_static_string: - * @string: (nullable): a static string - * - * Returns a canonical representation for @string. Interned strings - * can be compared for equality by comparing the pointers, instead of - * using strcmp(). g_intern_static_string() does not copy the string, - * therefore @string must not be freed or modified. - * - * This function must not be used before library constructors have finished - * running. In particular, this means it cannot be used to initialize global - * variables in C++. - * - * Returns: a canonical representation for the string - * Since: 2.10 - */ - - -/** - * g_intern_string: - * @string: (nullable): a string - * - * Returns a canonical representation for @string. Interned strings - * can be compared for equality by comparing the pointers, instead of - * using strcmp(). - * - * This function must not be used before library constructors have finished - * running. In particular, this means it cannot be used to initialize global - * variables in C++. - * - * Returns: a canonical representation for the string - * Since: 2.10 - */ - - -/** - * g_io_add_watch: - * @channel: a #GIOChannel - * @condition: the condition to watch for - * @func: the function to call when the condition is satisfied - * @user_data: user data to pass to @func - * - * Adds the #GIOChannel into the default main loop context - * with the default priority. - * - * Returns: the event source id - */ - - -/** - * g_io_add_watch_full: (rename-to g_io_add_watch) - * @channel: a #GIOChannel - * @priority: the priority of the #GIOChannel source - * @condition: the condition to watch for - * @func: the function to call when the condition is satisfied - * @user_data: user data to pass to @func - * @notify: the function to call when the source is removed - * - * Adds the #GIOChannel into the default main loop context - * with the given priority. - * - * This internally creates a main loop source using g_io_create_watch() - * and attaches it to the main loop context with g_source_attach(). - * You can do these steps manually if you need greater control. - * - * Returns: the event source id - */ - - -/** - * g_io_channel_close: - * @channel: A #GIOChannel - * - * Close an IO channel. Any pending data to be written will be - * flushed, ignoring errors. The channel will not be freed until the - * last reference is dropped using g_io_channel_unref(). - * - * Deprecated: 2.2: Use g_io_channel_shutdown() instead. - */ - - -/** - * g_io_channel_error_from_errno: - * @en: an `errno` error number, e.g. `EINVAL` - * - * Converts an `errno` error number to a #GIOChannelError. - * - * Returns: a #GIOChannelError error number, e.g. - * %G_IO_CHANNEL_ERROR_INVAL. - */ - - -/** - * g_io_channel_flush: - * @channel: a #GIOChannel - * @error: location to store an error of type #GIOChannelError - * - * Flushes the write buffer for the GIOChannel. - * - * Returns: the status of the operation: One of - * #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or - * #G_IO_STATUS_ERROR. - */ - - -/** - * g_io_channel_get_buffer_condition: - * @channel: A #GIOChannel - * - * This function returns a #GIOCondition depending on whether there - * is data to be read/space to write data in the internal buffers in - * the #GIOChannel. Only the flags %G_IO_IN and %G_IO_OUT may be set. - * - * Returns: A #GIOCondition - */ - - -/** - * g_io_channel_get_buffer_size: - * @channel: a #GIOChannel - * - * Gets the buffer size. - * - * Returns: the size of the buffer. - */ - - -/** - * g_io_channel_get_buffered: - * @channel: a #GIOChannel - * - * Returns whether @channel is buffered. - * - * Returns: %TRUE if the @channel is buffered. - */ - - -/** - * g_io_channel_get_close_on_unref: - * @channel: a #GIOChannel. - * - * Returns whether the file/socket/whatever associated with @channel - * will be closed when @channel receives its final unref and is - * destroyed. The default value of this is %TRUE for channels created - * by g_io_channel_new_file (), and %FALSE for all other channels. - * - * Returns: %TRUE if the channel will be closed, %FALSE otherwise. - */ - - -/** - * g_io_channel_get_encoding: - * @channel: a #GIOChannel - * - * Gets the encoding for the input/output of the channel. - * The internal encoding is always UTF-8. The encoding %NULL - * makes the channel safe for binary data. - * - * Returns: A string containing the encoding, this string is - * owned by GLib and must not be freed. - */ - - -/** - * g_io_channel_get_flags: - * @channel: a #GIOChannel - * - * Gets the current flags for a #GIOChannel, including read-only - * flags such as %G_IO_FLAG_IS_READABLE. - * - * The values of the flags %G_IO_FLAG_IS_READABLE and %G_IO_FLAG_IS_WRITABLE - * are cached for internal use by the channel when it is created. - * If they should change at some later point (e.g. partial shutdown - * of a socket with the UNIX shutdown() function), the user - * should immediately call g_io_channel_get_flags() to update - * the internal values of these flags. - * - * Returns: the flags which are set on the channel - */ - - -/** - * g_io_channel_get_line_term: - * @channel: a #GIOChannel - * @length: a location to return the length of the line terminator - * - * This returns the string that #GIOChannel uses to determine - * where in the file a line break occurs. A value of %NULL - * indicates autodetection. - * - * Returns: The line termination string. This value - * is owned by GLib and must not be freed. - */ - - -/** - * g_io_channel_init: - * @channel: a #GIOChannel - * - * Initializes a #GIOChannel struct. - * - * This is called by each of the above functions when creating a - * #GIOChannel, and so is not often needed by the application - * programmer (unless you are creating a new type of #GIOChannel). - */ - - -/** - * g_io_channel_new_file: - * @filename: (type filename): A string containing the name of a file - * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have - * the same meaning as in fopen() - * @error: A location to return an error of type %G_FILE_ERROR - * - * Open a file @filename as a #GIOChannel using mode @mode. This - * channel will be closed when the last reference to it is dropped, - * so there is no need to call g_io_channel_close() (though doing - * so will not cause problems, as long as no attempt is made to - * access the channel after it is closed). - * - * Returns: A #GIOChannel on success, %NULL on failure. - */ - - -/** - * g_io_channel_read: - * @channel: a #GIOChannel - * @buf: a buffer to read the data into (which should be at least - * count bytes long) - * @count: the number of bytes to read from the #GIOChannel - * @bytes_read: returns the number of bytes actually read - * - * Reads data from a #GIOChannel. - * - * Returns: %G_IO_ERROR_NONE if the operation was successful. - * Deprecated: 2.2: Use g_io_channel_read_chars() instead. - */ - - -/** - * g_io_channel_read_chars: - * @channel: a #GIOChannel - * @buf: (out caller-allocates) (array length=count) (element-type guint8): - * a buffer to read data into - * @count: (in): the size of the buffer. Note that the buffer may not be - * completely filled even if there is data in the buffer if the - * remaining data is not a complete character. - * @bytes_read: (out) (optional): The number of bytes read. This may be - * zero even on success if count < 6 and the channel's encoding - * is non-%NULL. This indicates that the next UTF-8 character is - * too wide for the buffer. - * @error: a location to return an error of type #GConvertError - * or #GIOChannelError. - * - * Replacement for g_io_channel_read() with the new API. - * - * Returns: the status of the operation. - */ - - -/** - * g_io_channel_read_line: - * @channel: a #GIOChannel - * @str_return: (out): The line read from the #GIOChannel, including the - * line terminator. This data should be freed with g_free() - * when no longer needed. This is a nul-terminated string. - * If a @length of zero is returned, this will be %NULL instead. - * @length: (out) (optional): location to store length of the read data, or %NULL - * @terminator_pos: (out) (optional): location to store position of line terminator, or %NULL - * @error: A location to return an error of type #GConvertError - * or #GIOChannelError - * - * Reads a line, including the terminating character(s), - * from a #GIOChannel into a newly-allocated string. - * @str_return will contain allocated memory if the return - * is %G_IO_STATUS_NORMAL. - * - * Returns: the status of the operation. - */ - - -/** - * g_io_channel_read_line_string: - * @channel: a #GIOChannel - * @buffer: a #GString into which the line will be written. - * If @buffer already contains data, the old data will - * be overwritten. - * @terminator_pos: (nullable): location to store position of line terminator, or %NULL - * @error: a location to store an error of type #GConvertError - * or #GIOChannelError - * - * Reads a line from a #GIOChannel, using a #GString as a buffer. - * - * Returns: the status of the operation. - */ - - -/** - * g_io_channel_read_to_end: - * @channel: a #GIOChannel - * @str_return: (out) (array length=length) (element-type guint8): Location to - * store a pointer to a string holding the remaining data in the - * #GIOChannel. This data should be freed with g_free() when no - * longer needed. This data is terminated by an extra nul - * character, but there may be other nuls in the intervening data. - * @length: (out): location to store length of the data - * @error: location to return an error of type #GConvertError - * or #GIOChannelError - * - * Reads all the remaining data from the file. - * - * Returns: %G_IO_STATUS_NORMAL on success. - * This function never returns %G_IO_STATUS_EOF. - */ - - -/** - * g_io_channel_read_unichar: - * @channel: a #GIOChannel - * @thechar: (out): a location to return a character - * @error: a location to return an error of type #GConvertError - * or #GIOChannelError - * - * Reads a Unicode character from @channel. - * This function cannot be called on a channel with %NULL encoding. - * - * Returns: a #GIOStatus - */ - - -/** - * g_io_channel_ref: - * @channel: a #GIOChannel - * - * Increments the reference count of a #GIOChannel. - * - * Returns: the @channel that was passed in (since 2.6) - */ - - -/** - * g_io_channel_seek: - * @channel: a #GIOChannel - * @offset: an offset, in bytes, which is added to the position specified - * by @type - * @type: the position in the file, which can be %G_SEEK_CUR (the current - * position), %G_SEEK_SET (the start of the file), or %G_SEEK_END - * (the end of the file) - * - * Sets the current position in the #GIOChannel, similar to the standard - * library function fseek(). - * - * Returns: %G_IO_ERROR_NONE if the operation was successful. - * Deprecated: 2.2: Use g_io_channel_seek_position() instead. - */ - - -/** - * g_io_channel_seek_position: - * @channel: a #GIOChannel - * @offset: The offset in bytes from the position specified by @type - * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those - * cases where a call to g_io_channel_set_encoding () - * is allowed. See the documentation for - * g_io_channel_set_encoding () for details. - * @error: A location to return an error of type #GIOChannelError - * - * Replacement for g_io_channel_seek() with the new API. - * - * Returns: the status of the operation. - */ - - -/** - * g_io_channel_set_buffer_size: - * @channel: a #GIOChannel - * @size: the size of the buffer, or 0 to let GLib pick a good size - * - * Sets the buffer size. - */ - - -/** - * g_io_channel_set_buffered: - * @channel: a #GIOChannel - * @buffered: whether to set the channel buffered or unbuffered - * - * The buffering state can only be set if the channel's encoding - * is %NULL. For any other encoding, the channel must be buffered. - * - * A buffered channel can only be set unbuffered if the channel's - * internal buffers have been flushed. Newly created channels or - * channels which have returned %G_IO_STATUS_EOF - * not require such a flush. For write-only channels, a call to - * g_io_channel_flush () is sufficient. For all other channels, - * the buffers may be flushed by a call to g_io_channel_seek_position (). - * This includes the possibility of seeking with seek type %G_SEEK_CUR - * and an offset of zero. Note that this means that socket-based - * channels cannot be set unbuffered once they have had data - * read from them. - * - * On unbuffered channels, it is safe to mix read and write - * calls from the new and old APIs, if this is necessary for - * maintaining old code. - * - * The default state of the channel is buffered. - */ - - -/** - * g_io_channel_set_close_on_unref: - * @channel: a #GIOChannel - * @do_close: Whether to close the channel on the final unref of - * the GIOChannel data structure. - * - * Whether to close the channel on the final unref of the #GIOChannel - * data structure. The default value of this is %TRUE for channels - * created by g_io_channel_new_file (), and %FALSE for all other channels. - * - * Setting this flag to %TRUE for a channel you have already closed - * can cause problems when the final reference to the #GIOChannel is dropped. - */ - - -/** - * g_io_channel_set_encoding: - * @channel: a #GIOChannel - * @encoding: (nullable): the encoding type - * @error: location to store an error of type #GConvertError - * - * Sets the encoding for the input/output of the channel. - * The internal encoding is always UTF-8. The default encoding - * for the external file is UTF-8. - * - * The encoding %NULL is safe to use with binary data. - * - * The encoding can only be set if one of the following conditions - * is true: - * - * - The channel was just created, and has not been written to or read from yet. - * - * - The channel is write-only. - * - * - The channel is a file, and the file pointer was just repositioned - * by a call to g_io_channel_seek_position(). (This flushes all the - * internal buffers.) - * - * - The current encoding is %NULL or UTF-8. - * - * - One of the (new API) read functions has just returned %G_IO_STATUS_EOF - * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL). - * - * - One of the functions g_io_channel_read_chars() or - * g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or - * %G_IO_STATUS_ERROR. This may be useful in the case of - * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. - * Returning one of these statuses from g_io_channel_read_line(), - * g_io_channel_read_line_string(), or g_io_channel_read_to_end() - * does not guarantee that the encoding can be changed. - * - * Channels which do not meet one of the above conditions cannot call - * g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if - * they are "seekable", cannot call g_io_channel_write_chars() after - * calling one of the API "read" functions. - * - * Returns: %G_IO_STATUS_NORMAL if the encoding was successfully set - */ - - -/** - * g_io_channel_set_flags: - * @channel: a #GIOChannel - * @flags: the flags to set on the IO channel - * @error: A location to return an error of type #GIOChannelError - * - * Sets the (writeable) flags in @channel to (@flags & %G_IO_FLAG_SET_MASK). - * - * Returns: the status of the operation. - */ - - -/** - * g_io_channel_set_line_term: - * @channel: a #GIOChannel - * @line_term: (nullable): The line termination string. Use %NULL for - * autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", - * and the Unicode paragraph separator. Autodetection should not be - * used for anything other than file-based channels. - * @length: The length of the termination string. If -1 is passed, the - * string is assumed to be nul-terminated. This option allows - * termination strings with embedded nuls. - * - * This sets the string that #GIOChannel uses to determine - * where in the file a line break occurs. - */ - - -/** - * g_io_channel_shutdown: - * @channel: a #GIOChannel - * @flush: if %TRUE, flush pending - * @err: location to store a #GIOChannelError - * - * Close an IO channel. Any pending data to be written will be - * flushed if @flush is %TRUE. The channel will not be freed until the - * last reference is dropped using g_io_channel_unref(). - * - * Returns: the status of the operation. - */ - - -/** - * g_io_channel_unix_get_fd: - * @channel: a #GIOChannel, created with g_io_channel_unix_new(). - * - * Returns the file descriptor of the #GIOChannel. - * - * On Windows this function returns the file descriptor or socket of - * the #GIOChannel. - * - * Returns: the file descriptor of the #GIOChannel. - */ - - -/** - * g_io_channel_unix_new: - * @fd: a file descriptor. - * - * Creates a new #GIOChannel given a file descriptor. On UNIX systems - * this works for plain files, pipes, and sockets. - * - * The returned #GIOChannel has a reference count of 1. - * - * The default encoding for #GIOChannel is UTF-8. If your application - * is reading output from a command using via pipe, you may need to set - * the encoding to the encoding of the current locale (see - * g_get_charset()) with the g_io_channel_set_encoding() function. - * By default, the fd passed will not be closed when the final reference - * to the #GIOChannel data structure is dropped. - * - * If you want to read raw binary data without interpretation, then - * call the g_io_channel_set_encoding() function with %NULL for the - * encoding argument. - * - * This function is available in GLib on Windows, too, but you should - * avoid using it on Windows. The domain of file descriptors and - * sockets overlap. There is no way for GLib to know which one you mean - * in case the argument you pass to this function happens to be both a - * valid file descriptor and socket. If that happens a warning is - * issued, and GLib assumes that it is the file descriptor you mean. - * - * Returns: a new #GIOChannel. - */ - - -/** - * g_io_channel_unref: - * @channel: a #GIOChannel - * - * Decrements the reference count of a #GIOChannel. - */ - - -/** - * g_io_channel_win32_new_fd: - * @fd: a C library file descriptor. - * - * Creates a new #GIOChannel given a file descriptor on Windows. This - * works for file descriptors from the C runtime. - * - * This function works for file descriptors as returned by the open(), - * creat(), pipe() and fileno() calls in the Microsoft C runtime. In - * order to meaningfully use this function your code should use the - * same C runtime as GLib uses, which is msvcrt.dll. Note that in - * current Microsoft compilers it is near impossible to convince it to - * build code that would use msvcrt.dll. The last Microsoft compiler - * version that supported using msvcrt.dll as the C runtime was version 6. - * The GNU compiler and toolchain for Windows, also known as Mingw, - * fully supports msvcrt.dll. - * - * If you have created a #GIOChannel for a file descriptor and started - * watching (polling) it, you shouldn't call read() on the file - * descriptor. This is because adding polling for a file descriptor is - * implemented in GLib on Windows by starting a thread that sits - * blocked in a read() from the file descriptor most of the time. All - * reads from the file descriptor should be done by this internal GLib - * thread. Your code should call only g_io_channel_read(). - * - * This function is available only in GLib on Windows. - * - * Returns: a new #GIOChannel. - */ - - -/** - * g_io_channel_win32_new_messages: - * @hwnd: a window handle. - * - * Creates a new #GIOChannel given a window handle on Windows. - * - * This function creates a #GIOChannel that can be used to poll for - * Windows messages for the window in question. - * - * Returns: a new #GIOChannel. - */ - - -/** - * g_io_channel_win32_new_socket: - * @socket: a Winsock socket - * - * Creates a new #GIOChannel given a socket on Windows. - * - * This function works for sockets created by Winsock. It's available - * only in GLib on Windows. - * - * Polling a #GSource created to watch a channel for a socket puts the - * socket in non-blocking mode. This is a side-effect of the - * implementation and unavoidable. - * - * Returns: a new #GIOChannel - */ - - -/** - * g_io_channel_write: - * @channel: a #GIOChannel - * @buf: the buffer containing the data to write - * @count: the number of bytes to write - * @bytes_written: the number of bytes actually written - * - * Writes data to a #GIOChannel. - * - * Returns: %G_IO_ERROR_NONE if the operation was successful. - * Deprecated: 2.2: Use g_io_channel_write_chars() instead. - */ - - -/** - * g_io_channel_write_chars: - * @channel: a #GIOChannel - * @buf: (array) (element-type guint8): a buffer to write data from - * @count: the size of the buffer. If -1, the buffer - * is taken to be a nul-terminated string. - * @bytes_written: (out): The number of bytes written. This can be nonzero - * even if the return value is not %G_IO_STATUS_NORMAL. - * If the return value is %G_IO_STATUS_NORMAL and the - * channel is blocking, this will always be equal - * to @count if @count >= 0. - * @error: a location to return an error of type #GConvertError - * or #GIOChannelError - * - * Replacement for g_io_channel_write() with the new API. - * - * On seekable channels with encodings other than %NULL or UTF-8, generic - * mixing of reading and writing is not allowed. A call to g_io_channel_write_chars () - * may only be made on a channel from which data has been read in the - * cases described in the documentation for g_io_channel_set_encoding (). - * - * Returns: the status of the operation. - */ - - -/** - * g_io_channel_write_unichar: - * @channel: a #GIOChannel - * @thechar: a character - * @error: location to return an error of type #GConvertError - * or #GIOChannelError - * - * Writes a Unicode character to @channel. - * This function cannot be called on a channel with %NULL encoding. - * - * Returns: a #GIOStatus - */ - - -/** - * g_io_create_watch: - * @channel: a #GIOChannel to watch - * @condition: conditions to watch for - * - * Creates a #GSource that's dispatched when @condition is met for the - * given @channel. For example, if condition is #G_IO_IN, the source will - * be dispatched when there's data available for reading. - * - * The callback function invoked by the #GSource should be added with - * g_source_set_callback(), but it has type #GIOFunc (not #GSourceFunc). - * - * g_io_add_watch() is a simpler interface to this same functionality, for - * the case where you want to add the source to the default main loop context - * at the default priority. - * - * On Windows, polling a #GSource created to watch a channel for a socket - * puts the socket in non-blocking mode. This is a side-effect of the - * implementation and unavoidable. - * - * Returns: a new #GSource - */ - - -/** - * g_key_file_free: (skip) - * @key_file: a #GKeyFile - * - * Clears all keys and groups from @key_file, and decreases the - * reference count by 1. If the reference count reaches zero, - * frees the key file and all its allocated memory. - * - * Since: 2.6 - */ - - -/** - * g_key_file_get_boolean: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @error: return location for a #GError - * - * Returns the value associated with @key under @group_name as a - * boolean. - * - * If @key cannot be found then %FALSE is returned and @error is set - * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value - * associated with @key cannot be interpreted as a boolean then %FALSE - * is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - * - * Returns: the value associated with the key as a boolean, - * or %FALSE if the key was not found or could not be parsed. - * Since: 2.6 - */ - - -/** - * g_key_file_get_boolean_list: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @length: (out): the number of booleans returned - * @error: return location for a #GError - * - * Returns the values associated with @key under @group_name as - * booleans. - * - * If @key cannot be found then %NULL is returned and @error is set to - * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated - * with @key cannot be interpreted as booleans then %NULL is returned - * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - * - * Returns: (array length=length) (element-type gboolean) (transfer container): - * the values associated with the key as a list of booleans, or %NULL if the - * key was not found or could not be parsed. The returned list of booleans - * should be freed with g_free() when no longer needed. - * Since: 2.6 - */ - - -/** - * g_key_file_get_comment: - * @key_file: a #GKeyFile - * @group_name: (nullable): a group name, or %NULL - * @key: (nullable): a key - * @error: return location for a #GError - * - * Retrieves a comment above @key from @group_name. - * If @key is %NULL then @comment will be read from above - * @group_name. If both @key and @group_name are %NULL, then - * @comment will be read from above the first group in the file. - * - * Note that the returned string does not include the '#' comment markers, - * but does include any whitespace after them (on each line). It includes - * the line breaks between lines, but does not include the final line break. - * - * Returns: a comment that should be freed with g_free() - * Since: 2.6 - */ - - -/** - * g_key_file_get_double: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @error: return location for a #GError - * - * Returns the value associated with @key under @group_name as a - * double. If @group_name is %NULL, the start_group is used. - * - * If @key cannot be found then 0.0 is returned and @error is set to - * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated - * with @key cannot be interpreted as a double then 0.0 is returned - * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - * - * Returns: the value associated with the key as a double, or - * 0.0 if the key was not found or could not be parsed. - * Since: 2.12 - */ - - -/** - * g_key_file_get_double_list: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @length: (out): the number of doubles returned - * @error: return location for a #GError - * - * Returns the values associated with @key under @group_name as - * doubles. - * - * If @key cannot be found then %NULL is returned and @error is set to - * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated - * with @key cannot be interpreted as doubles then %NULL is returned - * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - * - * Returns: (array length=length) (element-type gdouble) (transfer container): - * the values associated with the key as a list of doubles, or %NULL if the - * key was not found or could not be parsed. The returned list of doubles - * should be freed with g_free() when no longer needed. - * Since: 2.12 - */ - - -/** - * g_key_file_get_groups: - * @key_file: a #GKeyFile - * @length: (out) (optional): return location for the number of returned groups, or %NULL - * - * Returns all groups in the key file loaded with @key_file. - * The array of returned groups will be %NULL-terminated, so - * @length may optionally be %NULL. - * - * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. - * Use g_strfreev() to free it. - * Since: 2.6 - */ - - -/** - * g_key_file_get_int64: - * @key_file: a non-%NULL #GKeyFile - * @group_name: a non-%NULL group name - * @key: a non-%NULL key - * @error: return location for a #GError - * - * Returns the value associated with @key under @group_name as a signed - * 64-bit integer. This is similar to g_key_file_get_integer() but can return - * 64-bit results without truncation. - * - * Returns: the value associated with the key as a signed 64-bit integer, or - * 0 if the key was not found or could not be parsed. - * Since: 2.26 - */ - - -/** - * g_key_file_get_integer: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @error: return location for a #GError - * - * Returns the value associated with @key under @group_name as an - * integer. - * - * If @key cannot be found then 0 is returned and @error is set to - * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated - * with @key cannot be interpreted as an integer, or is out of range - * for a #gint, then 0 is returned - * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - * - * Returns: the value associated with the key as an integer, or - * 0 if the key was not found or could not be parsed. - * Since: 2.6 - */ - - -/** - * g_key_file_get_integer_list: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @length: (out): the number of integers returned - * @error: return location for a #GError - * - * Returns the values associated with @key under @group_name as - * integers. - * - * If @key cannot be found then %NULL is returned and @error is set to - * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated - * with @key cannot be interpreted as integers, or are out of range for - * #gint, then %NULL is returned - * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. - * - * Returns: (array length=length) (element-type gint) (transfer container): - * the values associated with the key as a list of integers, or %NULL if - * the key was not found or could not be parsed. The returned list of - * integers should be freed with g_free() when no longer needed. - * Since: 2.6 - */ - - -/** - * g_key_file_get_keys: - * @key_file: a #GKeyFile - * @group_name: a group name - * @length: (out) (optional): return location for the number of keys returned, or %NULL - * @error: return location for a #GError, or %NULL - * - * Returns all keys for the group name @group_name. The array of - * returned keys will be %NULL-terminated, so @length may - * optionally be %NULL. In the event that the @group_name cannot - * be found, %NULL is returned and @error is set to - * #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - * - * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. - * Use g_strfreev() to free it. - * Since: 2.6 - */ - - -/** - * g_key_file_get_locale_for_key: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @locale: (nullable): a locale identifier or %NULL - * - * Returns the actual locale which the result of - * g_key_file_get_locale_string() or g_key_file_get_locale_string_list() - * came from. - * - * If calling g_key_file_get_locale_string() or - * g_key_file_get_locale_string_list() with exactly the same @key_file, - * @group_name, @key and @locale, the result of those functions will - * have originally been tagged with the locale that is the result of - * this function. - * - * Returns: (nullable): the locale from the file, or %NULL if the key was not - * found or the entry in the file was was untranslated - * Since: 2.56 - */ - - -/** - * g_key_file_get_locale_string: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @locale: (nullable): a locale identifier or %NULL - * @error: return location for a #GError, or %NULL - * - * Returns the value associated with @key under @group_name - * translated in the given @locale if available. If @locale is - * %NULL then the current locale is assumed. - * - * If @locale is to be non-%NULL, or if the current locale will change over - * the lifetime of the #GKeyFile, it must be loaded with - * %G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales. - * - * If @key cannot be found then %NULL is returned and @error is set - * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated - * with @key cannot be interpreted or no suitable translation can - * be found then the untranslated value is returned. - * - * Returns: a newly allocated string or %NULL if the specified - * key cannot be found. - * Since: 2.6 - */ - - -/** - * g_key_file_get_locale_string_list: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @locale: (nullable): a locale identifier or %NULL - * @length: (out) (optional): return location for the number of returned strings or %NULL - * @error: return location for a #GError or %NULL - * - * Returns the values associated with @key under @group_name - * translated in the given @locale if available. If @locale is - * %NULL then the current locale is assumed. - * - * If @locale is to be non-%NULL, or if the current locale will change over - * the lifetime of the #GKeyFile, it must be loaded with - * %G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales. - * - * If @key cannot be found then %NULL is returned and @error is set - * to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated - * with @key cannot be interpreted or no suitable translations - * can be found then the untranslated values are returned. The - * returned array is %NULL-terminated, so @length may optionally - * be %NULL. - * - * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array - * or %NULL if the key isn't found. The string array should be freed - * with g_strfreev(). - * Since: 2.6 - */ - - -/** - * g_key_file_get_start_group: - * @key_file: a #GKeyFile - * - * Returns the name of the start group of the file. - * - * Returns: (nullable): The start group of the key file. - * Since: 2.6 - */ - - -/** - * g_key_file_get_string: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @error: return location for a #GError, or %NULL - * - * Returns the string value associated with @key under @group_name. - * Unlike g_key_file_get_value(), this function handles escape sequences - * like \s. - * - * In the event the key cannot be found, %NULL is returned and - * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the - * event that the @group_name cannot be found, %NULL is returned - * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - * - * Returns: a newly allocated string or %NULL if the specified - * key cannot be found. - * Since: 2.6 - */ - - -/** - * g_key_file_get_string_list: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @length: (out) (optional): return location for the number of returned strings, or %NULL - * @error: return location for a #GError, or %NULL - * - * Returns the values associated with @key under @group_name. - * - * In the event the key cannot be found, %NULL is returned and - * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the - * event that the @group_name cannot be found, %NULL is returned - * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - * - * 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.6 - */ - - -/** - * g_key_file_get_uint64: - * @key_file: a non-%NULL #GKeyFile - * @group_name: a non-%NULL group name - * @key: a non-%NULL key - * @error: return location for a #GError - * - * Returns the value associated with @key under @group_name as an unsigned - * 64-bit integer. This is similar to g_key_file_get_integer() but can return - * large positive results without truncation. - * - * Returns: the value associated with the key as an unsigned 64-bit integer, - * or 0 if the key was not found or could not be parsed. - * Since: 2.26 - */ - - -/** - * g_key_file_get_value: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @error: return location for a #GError, or %NULL - * - * Returns the raw value associated with @key under @group_name. - * Use g_key_file_get_string() to retrieve an unescaped UTF-8 string. - * - * In the event the key cannot be found, %NULL is returned and - * @error is set to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. In the - * event that the @group_name cannot be found, %NULL is returned - * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. - * - * Returns: a newly allocated string or %NULL if the specified - * key cannot be found. - * Since: 2.6 - */ - - -/** - * g_key_file_has_group: - * @key_file: a #GKeyFile - * @group_name: a group name - * - * Looks whether the key file has the group @group_name. - * - * Returns: %TRUE if @group_name is a part of @key_file, %FALSE - * otherwise. - * Since: 2.6 - */ - - -/** - * g_key_file_has_key: (skip) - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key name - * @error: return location for a #GError - * - * Looks whether the key file has the key @key in the group - * @group_name. - * - * Note that this function does not follow the rules for #GError strictly; - * the return value both carries meaning and signals an error. To use - * this function, you must pass a #GError pointer in @error, and check - * whether it is not %NULL to see if an error occurred. - * - * Language bindings should use g_key_file_get_value() to test whether - * or not a key exists. - * - * Returns: %TRUE if @key is a part of @group_name, %FALSE otherwise - * Since: 2.6 - */ - - -/** - * g_key_file_load_from_bytes: - * @key_file: an empty #GKeyFile struct - * @bytes: a #GBytes - * @flags: flags from #GKeyFileFlags - * @error: return location for a #GError, or %NULL - * - * Loads a key file from the data in @bytes into an empty #GKeyFile structure. - * If the object cannot be created then %error is set to a #GKeyFileError. - * - * Returns: %TRUE if a key file could be loaded, %FALSE otherwise - * Since: 2.50 - */ - - -/** - * g_key_file_load_from_data: - * @key_file: an empty #GKeyFile struct - * @data: key file loaded in memory - * @length: the length of @data in bytes (or (gsize)-1 if data is nul-terminated) - * @flags: flags from #GKeyFileFlags - * @error: return location for a #GError, or %NULL - * - * Loads a key file from memory into an empty #GKeyFile structure. - * If the object cannot be created then %error is set to a #GKeyFileError. - * - * Returns: %TRUE if a key file could be loaded, %FALSE otherwise - * Since: 2.6 - */ - - -/** - * g_key_file_load_from_data_dirs: - * @key_file: an empty #GKeyFile struct - * @file: (type filename): a relative path to a filename to open and parse - * @full_path: (out) (type filename) (optional): return location for a string containing the full path - * of the file, or %NULL - * @flags: flags from #GKeyFileFlags - * @error: return location for a #GError, or %NULL - * - * This function looks for a key file named @file in the paths - * returned from g_get_user_data_dir() and g_get_system_data_dirs(), - * loads the file into @key_file and returns the file's full path in - * @full_path. If the file could not be loaded then an %error is - * set to either a #GFileError or #GKeyFileError. - * - * Returns: %TRUE if a key file could be loaded, %FALSE otherwise - * Since: 2.6 - */ - - -/** - * g_key_file_load_from_dirs: - * @key_file: an empty #GKeyFile struct - * @file: (type filename): a relative path to a filename to open and parse - * @search_dirs: (array zero-terminated=1) (element-type filename): %NULL-terminated array of directories to search - * @full_path: (out) (type filename) (optional): return location for a string containing the full path - * of the file, or %NULL - * @flags: flags from #GKeyFileFlags - * @error: return location for a #GError, or %NULL - * - * This function looks for a key file named @file in the paths - * specified in @search_dirs, loads the file into @key_file and - * returns the file's full path in @full_path. - * - * If the file could not be found in any of the @search_dirs, - * %G_KEY_FILE_ERROR_NOT_FOUND is returned. If - * the file is found but the OS returns an error when opening or reading the - * file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a - * %G_KEY_FILE_ERROR is returned. - * - * Returns: %TRUE if a key file could be loaded, %FALSE otherwise - * Since: 2.14 - */ - - -/** - * g_key_file_load_from_file: - * @key_file: an empty #GKeyFile struct - * @file: (type filename): the path of a filename to load, in the GLib filename encoding - * @flags: flags from #GKeyFileFlags - * @error: return location for a #GError, or %NULL - * - * Loads a key file into an empty #GKeyFile structure. - * - * If the OS returns an error when opening or reading the file, a - * %G_FILE_ERROR is returned. If there is a problem parsing the file, a - * %G_KEY_FILE_ERROR is returned. - * - * This function will never return a %G_KEY_FILE_ERROR_NOT_FOUND error. If the - * @file is not found, %G_FILE_ERROR_NOENT is returned. - * - * Returns: %TRUE if a key file could be loaded, %FALSE otherwise - * Since: 2.6 - */ - - -/** - * g_key_file_new: - * - * Creates a new empty #GKeyFile object. Use - * g_key_file_load_from_file(), g_key_file_load_from_data(), - * g_key_file_load_from_dirs() or g_key_file_load_from_data_dirs() to - * read an existing key file. - * - * Returns: (transfer full): an empty #GKeyFile. - * Since: 2.6 - */ - - -/** - * g_key_file_ref: (skip) - * @key_file: a #GKeyFile - * - * Increases the reference count of @key_file. - * - * Returns: the same @key_file. - * Since: 2.32 - */ - - -/** - * g_key_file_remove_comment: - * @key_file: a #GKeyFile - * @group_name: (nullable): a group name, or %NULL - * @key: (nullable): a key - * @error: return location for a #GError - * - * Removes a comment above @key from @group_name. - * If @key is %NULL then @comment will be removed above @group_name. - * If both @key and @group_name are %NULL, then @comment will - * be removed above the first group in the file. - * - * Returns: %TRUE if the comment was removed, %FALSE otherwise - * Since: 2.6 - */ - - -/** - * g_key_file_remove_group: - * @key_file: a #GKeyFile - * @group_name: a group name - * @error: return location for a #GError or %NULL - * - * Removes the specified group, @group_name, - * from the key file. - * - * Returns: %TRUE if the group was removed, %FALSE otherwise - * Since: 2.6 - */ - - -/** - * g_key_file_remove_key: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key name to remove - * @error: return location for a #GError or %NULL - * - * Removes @key in @group_name from the key file. - * - * Returns: %TRUE if the key was removed, %FALSE otherwise - * Since: 2.6 - */ - - -/** - * g_key_file_save_to_file: - * @key_file: a #GKeyFile - * @filename: the name of the file to write to - * @error: a pointer to a %NULL #GError, or %NULL - * - * Writes the contents of @key_file to @filename using - * g_file_set_contents(). If you need stricter guarantees about durability of - * the written file than are provided by g_file_set_contents(), use - * g_file_set_contents_full() with the return value of g_key_file_to_data(). - * - * This function can fail for any of the reasons that - * g_file_set_contents() may fail. - * - * Returns: %TRUE if successful, else %FALSE with @error set - * Since: 2.40 - */ - - -/** - * g_key_file_set_boolean: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @value: %TRUE or %FALSE - * - * Associates a new boolean value with @key under @group_name. - * If @key cannot be found then it is created. - * - * Since: 2.6 - */ - - -/** - * g_key_file_set_boolean_list: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @list: (array length=length): an array of boolean values - * @length: length of @list - * - * Associates a list of boolean values with @key under @group_name. - * If @key cannot be found then it is created. - * If @group_name is %NULL, the start_group is used. - * - * Since: 2.6 - */ - - -/** - * g_key_file_set_comment: - * @key_file: a #GKeyFile - * @group_name: (nullable): a group name, or %NULL - * @key: (nullable): a key - * @comment: a comment - * @error: return location for a #GError - * - * Places a comment above @key from @group_name. - * - * If @key is %NULL then @comment will be written above @group_name. - * If both @key and @group_name are %NULL, then @comment will be - * written above the first group in the file. - * - * Note that this function prepends a '#' comment marker to - * each line of @comment. - * - * Returns: %TRUE if the comment was written, %FALSE otherwise - * Since: 2.6 - */ - - -/** - * g_key_file_set_double: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @value: a double value - * - * Associates a new double value with @key under @group_name. - * If @key cannot be found then it is created. - * - * Since: 2.12 - */ - - -/** - * g_key_file_set_double_list: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @list: (array length=length): an array of double values - * @length: number of double values in @list - * - * Associates a list of double values with @key under - * @group_name. If @key cannot be found then it is created. - * - * Since: 2.12 - */ - - -/** - * g_key_file_set_int64: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @value: an integer value - * - * Associates a new integer value with @key under @group_name. - * If @key cannot be found then it is created. - * - * Since: 2.26 - */ - - -/** - * g_key_file_set_integer: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @value: an integer value - * - * Associates a new integer value with @key under @group_name. - * If @key cannot be found then it is created. - * - * Since: 2.6 - */ - - -/** - * g_key_file_set_integer_list: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @list: (array length=length): an array of integer values - * @length: number of integer values in @list - * - * Associates a list of integer values with @key under @group_name. - * If @key cannot be found then it is created. - * - * Since: 2.6 - */ - - -/** - * g_key_file_set_list_separator: - * @key_file: a #GKeyFile - * @separator: the separator - * - * Sets the character which is used to separate - * values in lists. Typically ';' or ',' are used - * as separators. The default list separator is ';'. - * - * Since: 2.6 - */ - - -/** - * g_key_file_set_locale_string: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @locale: a locale identifier - * @string: a string - * - * Associates a string value for @key and @locale under @group_name. - * If the translation for @key cannot be found then it is created. - * - * Since: 2.6 - */ - - -/** - * g_key_file_set_locale_string_list: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @locale: a locale identifier - * @list: (array zero-terminated=1 length=length): a %NULL-terminated array of locale string values - * @length: the length of @list - * - * Associates a list of string values for @key and @locale under - * @group_name. If the translation for @key cannot be found then - * it is created. - * - * Since: 2.6 - */ - - -/** - * g_key_file_set_string: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @string: a string - * - * Associates a new string value with @key under @group_name. - * If @key cannot be found then it is created. - * If @group_name cannot be found then it is created. - * Unlike g_key_file_set_value(), this function handles characters - * that need escaping, such as newlines. - * - * Since: 2.6 - */ - - -/** - * g_key_file_set_string_list: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @list: (array zero-terminated=1 length=length) (element-type utf8): an array of string values - * @length: number of string values in @list - * - * Associates a list of string values for @key under @group_name. - * If @key cannot be found then it is created. - * If @group_name cannot be found then it is created. - * - * Since: 2.6 - */ - - -/** - * g_key_file_set_uint64: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @value: an integer value - * - * Associates a new integer value with @key under @group_name. - * If @key cannot be found then it is created. - * - * Since: 2.26 - */ - - -/** - * g_key_file_set_value: - * @key_file: a #GKeyFile - * @group_name: a group name - * @key: a key - * @value: a string - * - * Associates a new value with @key under @group_name. - * - * If @key cannot be found then it is created. If @group_name cannot - * be found then it is created. To set an UTF-8 string which may contain - * characters that need escaping (such as newlines or spaces), use - * g_key_file_set_string(). - * - * Since: 2.6 - */ - - -/** - * g_key_file_to_data: - * @key_file: a #GKeyFile - * @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 @key_file as a string. - * - * Note that this function never reports an error, - * so it is safe to pass %NULL as @error. - * - * Returns: a newly allocated string holding - * the contents of the #GKeyFile - * Since: 2.6 - */ - - -/** - * g_key_file_unref: - * @key_file: a #GKeyFile - * - * Decreases the reference count of @key_file by 1. If the reference count - * reaches zero, frees the key file and all its allocated memory. - * - * Since: 2.32 - */ - - -/** - * g_list_alloc: - * - * Allocates space for one #GList element. It is called by - * g_list_append(), g_list_prepend(), g_list_insert() and - * g_list_insert_sorted() and so is rarely used on its own. - * - * Returns: a pointer to the newly-allocated #GList element - */ - - -/** - * g_list_append: - * @list: a pointer to a #GList - * @data: the data for the new element - * - * Adds a new element on to the end of the list. - * - * Note that the return value is the new start of the list, - * if @list was empty; make sure you store the new value. - * - * g_list_append() has to traverse the entire list to find the end, - * which is inefficient when adding multiple elements. A common idiom - * to avoid the inefficiency is to use g_list_prepend() and reverse - * the list with g_list_reverse() when all elements have been added. - * - * |[<!-- language="C" --> - * // Notice that these are initialized to the empty list. - * GList *string_list = NULL, *number_list = NULL; - * - * // This is a list of strings. - * string_list = g_list_append (string_list, "first"); - * string_list = g_list_append (string_list, "second"); - * - * // This is a list of integers. - * number_list = g_list_append (number_list, GINT_TO_POINTER (27)); - * number_list = g_list_append (number_list, GINT_TO_POINTER (14)); - * ]| - * - * Returns: either @list or the new start of the #GList if @list was %NULL - */ - - -/** - * g_list_concat: - * @list1: a #GList, this must point to the top of the list - * @list2: the #GList to add to the end of the first #GList, - * this must point to the top of the list - * - * Adds the second #GList onto the end of the first #GList. - * Note that the elements of the second #GList are not copied. - * They are used directly. - * - * This function is for example used to move an element in the list. - * The following example moves an element to the top of the list: - * |[<!-- language="C" --> - * list = g_list_remove_link (list, llink); - * list = g_list_concat (llink, list); - * ]| - * - * Returns: the start of the new #GList, which equals @list1 if not %NULL - */ - - -/** - * g_list_copy: - * @list: a #GList, this must point to the top of the list - * - * Copies a #GList. - * - * Note that this is a "shallow" copy. If the list elements - * consist of pointers to data, the pointers are copied but - * the actual data is not. See g_list_copy_deep() if you need - * to copy the data as well. - * - * Returns: the start of the new list that holds the same data as @list - */ - - -/** - * g_list_copy_deep: - * @list: a #GList, this must point to the top of the list - * @func: a copy function used to copy every element in the list - * @user_data: user data passed to the copy function @func, or %NULL - * - * Makes a full (deep) copy of a #GList. - * - * In contrast with g_list_copy(), this function uses @func to make - * a copy of each list element, in addition to copying the list - * container itself. - * - * @func, as a #GCopyFunc, takes two arguments, the data to be copied - * and a @user_data pointer. On common processor architectures, it's safe to - * pass %NULL as @user_data if the copy function takes only one argument. You - * may get compiler warnings from this though if compiling with GCC’s - * `-Wcast-function-type` warning. - * - * For instance, if @list holds a list of GObjects, you can do: - * |[<!-- language="C" --> - * another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL); - * ]| - * - * And, to entirely free the new list, you could do: - * |[<!-- language="C" --> - * g_list_free_full (another_list, g_object_unref); - * ]| - * - * Returns: the start of the new list that holds a full copy of @list, - * use g_list_free_full() to free it - * Since: 2.34 - */ - - -/** - * g_list_delete_link: - * @list: a #GList, this must point to the top of the list - * @link_: node to delete from @list - * - * Removes the node link_ from the list and frees it. - * Compare this to g_list_remove_link() which removes the node - * without freeing it. - * - * Returns: the (possibly changed) start of the #GList - */ - - -/** - * g_list_find: - * @list: a #GList, this must point to the top of the list - * @data: the element data to find - * - * Finds the element in a #GList which contains the given data. - * - * Returns: the found #GList element, or %NULL if it is not found - */ - - -/** - * g_list_find_custom: - * @list: a #GList, this must point to the top of the list - * @data: user data passed to the function - * @func: the function to call for each element. - * It should return 0 when the desired element is found - * - * Finds an element in a #GList, using a supplied function to - * find the desired element. It iterates over the list, calling - * the given function which should return 0 when the desired - * element is found. The function takes two #gconstpointer arguments, - * the #GList element's data as the first argument and the - * given user data. - * - * Returns: the found #GList element, or %NULL if it is not found - */ - - -/** - * g_list_first: - * @list: any #GList element - * - * Gets the first element in a #GList. - * - * Returns: the first element in the #GList, - * or %NULL if the #GList has no elements - */ - - -/** - * g_list_foreach: - * @list: a #GList, this must point to the top of the list - * @func: the function to call with each element's data - * @user_data: user data to pass to the function - * - * Calls a function for each element of a #GList. - * - * It is safe for @func to remove the element from @list, but it must - * not modify any part of the list after that element. - */ - - -/** - * g_list_free: - * @list: the first link of a #GList - * - * Frees all of the memory used by a #GList. - * The freed elements are returned to the slice allocator. - * - * If list elements contain dynamically-allocated memory, you should - * either use g_list_free_full() or free them manually first. - * - * It can be combined with g_steal_pointer() to ensure the list head pointer - * is not left dangling: - * |[<!-- language="C" --> - * GList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/ - * g_list_free (g_steal_pointer (&list_of_borrowed_things)); - * ]| - */ - - -/** - * g_list_free1: - * - * Another name for g_list_free_1(). - */ - - -/** - * g_list_free_1: - * @list: a #GList element - * - * Frees one #GList element, but does not update links from the next and - * previous elements in the list, so you should not call this function on an - * element that is currently part of a list. - * - * It is usually used after g_list_remove_link(). - */ - - -/** - * g_list_free_full: - * @list: the first link of a #GList - * @free_func: the function to be called to free each element's data - * - * Convenience method, which frees all the memory used by a #GList, - * and calls @free_func on every element's data. - * - * @free_func must not modify the list (eg, by removing the freed - * element from it). - * - * It can be combined with g_steal_pointer() to ensure the list head pointer - * is not left dangling — this also has the nice property that the head pointer - * is cleared before any of the list elements are freed, to prevent double frees - * from @free_func: - * |[<!-- language="C" --> - * GList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/ - * g_list_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref); - * ]| - * - * Since: 2.28 - */ - - -/** - * g_list_index: - * @list: a #GList, this must point to the top of the list - * @data: the data to find - * - * Gets the position of the element containing - * the given data (starting from 0). - * - * Returns: the index of the element containing the data, - * or -1 if the data is not found - */ - - -/** - * g_list_insert: - * @list: a pointer to a #GList, this must point to the top of the list - * @data: the data for the new element - * @position: the position to insert the element. If this is - * negative, or is larger than the number of elements in the - * list, the new element is added on to the end of the list. - * - * Inserts a new element into the list at the given position. - * - * Returns: the (possibly changed) start of the #GList - */ - - -/** - * g_list_insert_before: - * @list: a pointer to a #GList, this must point to the top of the list - * @sibling: the list element before which the new element - * is inserted or %NULL to insert at the end of the list - * @data: the data for the new element - * - * Inserts a new element into the list before the given position. - * - * Returns: the (possibly changed) start of the #GList - */ - - -/** - * g_list_insert_before_link: - * @list: a pointer to a #GList, this must point to the top of the list - * @sibling: (nullable): the list element before which the new element - * is inserted or %NULL to insert at the end of the list - * @link_: the list element to be added, which must not be part of - * any other list - * - * Inserts @link_ into the list before the given position. - * - * Returns: the (possibly changed) start of the #GList - * Since: 2.62 - */ - - -/** - * g_list_insert_sorted: - * @list: a pointer to a #GList, this must point to the top of the - * already sorted list - * @data: the data for the new element - * @func: the function to compare elements in the list. It should - * return a number > 0 if the first parameter comes after the - * second parameter in the sort order. - * - * Inserts a new element into the list, using the given comparison - * function to determine its position. - * - * If you are adding many new elements to a list, and the number of - * new elements is much larger than the length of the list, use - * g_list_prepend() to add the new items and sort the list afterwards - * with g_list_sort(). - * - * Returns: the (possibly changed) start of the #GList - */ - - -/** - * g_list_insert_sorted_with_data: - * @list: a pointer to a #GList, this must point to the top of the - * already sorted list - * @data: the data for the new element - * @func: the function to compare elements in the list. It should - * return a number > 0 if the first parameter comes after the - * second parameter in the sort order. - * @user_data: user data to pass to comparison function - * - * Inserts a new element into the list, using the given comparison - * function to determine its position. - * - * If you are adding many new elements to a list, and the number of - * new elements is much larger than the length of the list, use - * g_list_prepend() to add the new items and sort the list afterwards - * with g_list_sort(). - * - * Returns: the (possibly changed) start of the #GList - * Since: 2.10 - */ - - -/** - * g_list_last: - * @list: any #GList element - * - * Gets the last element in a #GList. - * - * Returns: the last element in the #GList, - * or %NULL if the #GList has no elements - */ - - -/** - * g_list_length: - * @list: a #GList, this must point to the top of the list - * - * Gets the number of elements in a #GList. - * - * This function iterates over the whole list to count its elements. - * Use a #GQueue instead of a GList if you regularly need the number - * of items. To check whether the list is non-empty, it is faster to check - * @list against %NULL. - * - * Returns: the number of elements in the #GList - */ - - -/** - * g_list_next: - * @list: an element in a #GList - * - * A convenience macro to get the next element in a #GList. - * Note that it is considered perfectly acceptable to access - * @list->next directly. - * - * Returns: the next element, or %NULL if there are no more elements - */ - - -/** - * g_list_nth: - * @list: a #GList, this must point to the top of the list - * @n: the position of the element, counting from 0 - * - * Gets the element at the given position in a #GList. - * - * This iterates over the list until it reaches the @n-th position. If you - * intend to iterate over every element, it is better to use a for-loop as - * described in the #GList introduction. - * - * Returns: the element, or %NULL if the position is off - * the end of the #GList - */ - - -/** - * g_list_nth_data: - * @list: a #GList, this must point to the top of the list - * @n: the position of the element - * - * Gets the data of the element at the given position. - * - * This iterates over the list until it reaches the @n-th position. If you - * intend to iterate over every element, it is better to use a for-loop as - * described in the #GList introduction. - * - * Returns: the element's data, or %NULL if the position - * is off the end of the #GList - */ - - -/** - * g_list_nth_prev: - * @list: a #GList - * @n: the position of the element, counting from 0 - * - * Gets the element @n places before @list. - * - * Returns: the element, or %NULL if the position is - * off the end of the #GList - */ - - -/** - * g_list_position: - * @list: a #GList, this must point to the top of the list - * @llink: an element in the #GList - * - * Gets the position of the given element - * in the #GList (starting from 0). - * - * Returns: the position of the element in the #GList, - * or -1 if the element is not found - */ - - -/** - * g_list_prepend: - * @list: a pointer to a #GList, this must point to the top of the list - * @data: the data for the new element - * - * Prepends a new element on to the start of the list. - * - * Note that the return value is the new start of the list, - * which will have changed, so make sure you store the new value. - * - * |[<!-- language="C" --> - * // Notice that it is initialized to the empty list. - * GList *list = NULL; - * - * list = g_list_prepend (list, "last"); - * list = g_list_prepend (list, "first"); - * ]| - * - * Do not use this function to prepend a new element to a different - * element than the start of the list. Use g_list_insert_before() instead. - * - * Returns: a pointer to the newly prepended element, which is the new - * start of the #GList - */ - - -/** - * g_list_previous: - * @list: an element in a #GList - * - * A convenience macro to get the previous element in a #GList. - * Note that it is considered perfectly acceptable to access - * @list->prev directly. - * - * Returns: the previous element, or %NULL if there are no previous - * elements - */ - - -/** - * g_list_remove: - * @list: a #GList, this must point to the top of the list - * @data: the data of the element to remove - * - * Removes an element from a #GList. - * If two elements contain the same data, only the first is removed. - * If none of the elements contain the data, the #GList is unchanged. - * - * Returns: the (possibly changed) start of the #GList - */ - - -/** - * g_list_remove_all: - * @list: a #GList, this must point to the top of the list - * @data: data to remove - * - * Removes all list nodes with data equal to @data. - * Returns the new head of the list. Contrast with - * g_list_remove() which removes only the first node - * matching the given data. - * - * Returns: the (possibly changed) start of the #GList - */ - - -/** - * g_list_remove_link: - * @list: a #GList, this must point to the top of the list - * @llink: an element in the #GList - * - * Removes an element from a #GList, without freeing the element. - * The removed element's prev and next links are set to %NULL, so - * that it becomes a self-contained list with one element. - * - * This function is for example used to move an element in the list - * (see the example for g_list_concat()) or to remove an element in - * the list before freeing its data: - * |[<!-- language="C" --> - * list = g_list_remove_link (list, llink); - * free_some_data_that_may_access_the_list_again (llink->data); - * g_list_free (llink); - * ]| - * - * Returns: the (possibly changed) start of the #GList - */ - - -/** - * g_list_reverse: - * @list: a #GList, this must point to the top of the list - * - * Reverses a #GList. - * It simply switches the next and prev pointers of each element. - * - * Returns: the start of the reversed #GList - */ - - -/** - * g_list_sort: - * @list: a #GList, this must point to the top of the list - * @compare_func: the comparison function used to sort the #GList. - * This function is passed the data from 2 elements of the #GList - * and should return 0 if they are equal, a negative value if the - * first element comes before the second, or a positive value if - * the first element comes after the second. - * - * Sorts a #GList using the given comparison function. The algorithm - * used is a stable sort. - * - * Returns: the (possibly changed) start of the #GList - */ - - -/** - * g_list_sort_with_data: - * @list: a #GList, this must point to the top of the list - * @compare_func: comparison function - * @user_data: user data to pass to comparison function - * - * Like g_list_sort(), but the comparison function accepts - * a user data argument. - * - * Returns: the (possibly changed) start of the #GList - */ - - -/** - * g_listenv: - * - * Gets the names of all variables set in the environment. - * - * Programs that want to be portable to Windows should typically use - * this function and g_getenv() instead of using the environ array - * from the C library directly. On Windows, the strings in the environ - * array are in system codepage encoding, while in most of the typical - * use cases for environment variables in GLib-using programs you want - * the UTF-8 encoding that this function and g_getenv() provide. - * - * Returns: (array zero-terminated=1) (element-type filename) (transfer full): - * a %NULL-terminated list of strings which must be freed with - * g_strfreev(). - * Since: 2.8 - */ - - -/** - * g_locale_from_utf8: - * @utf8string: a UTF-8 encoded string - * @len: the length of the string, or -1 if the string is - * nul-terminated. - * @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 UTF-8 to the encoding used for strings by - * the C runtime (usually the same as that used by the operating - * system) in the [current locale][setlocale]. On Windows this means - * the system codepage. - * - * The input string shall not contain nul characters even if the @len - * argument is positive. A nul character found inside the string will result - * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Use g_convert() to convert - * input that may contain embedded nul characters. - * - * Returns: (array length=bytes_written) (element-type guint8) (transfer full): - * A newly-allocated buffer containing the converted string, - * or %NULL on an error, and error will be set. - */ - - -/** - * g_locale_to_utf8: - * @opsysstring: (array length=len) (element-type guint8): a string in the - * encoding of the current locale. On Windows - * this means the system codepage. - * @len: the length of the string, 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) - * @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 which is in the encoding used for strings by - * the C runtime (usually the same as that used by the operating - * system) in the [current locale][setlocale] into a UTF-8 string. - * - * If the source encoding is not UTF-8 and the conversion output contains a - * nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the - * function returns %NULL. - * If the source encoding is UTF-8, an embedded nul character is treated with - * the %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error for backward compatibility with - * earlier versions of this library. Use g_convert() to produce output that - * may contain embedded nul characters. - * - * Returns: (type utf8): The converted string, or %NULL on an error. - */ - - -/** - * g_log: - * @log_domain: (nullable): the log domain, usually %G_LOG_DOMAIN, or %NULL - * for the default - * @log_level: the log level, either from #GLogLevelFlags - * or a user-defined level - * @format: the message format. See the `printf()` documentation - * @...: the parameters to insert into the format string - * - * Logs an error or debugging message. - * - * If the log level has been set as fatal, G_BREAKPOINT() is called - * to terminate the program. See the documentation for G_BREAKPOINT() for - * details of the debugging options this provides. - * - * 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][using-structured-logging] this will - * output via the structured log writer function (see g_log_set_writer_func()). - */ - - -/** - * g_log_default_handler: - * @log_domain: (nullable): the log domain of the message, or %NULL for the - * default "" application domain - * @log_level: the level of the message - * @message: (nullable): the message - * @unused_data: (nullable): data passed from g_log() which is unused - * - * The default log handler set up by GLib; g_log_set_default_handler() - * allows to install an alternate default log handler. - * This is used if no log handler has been set for the particular log - * domain and log level combination. It outputs the message to stderr - * or stdout and if the log level is fatal it calls G_BREAKPOINT(). It automatically - * prints a new-line character after the message, so one does not need to be - * manually included in @message. - * - * The behavior of this log handler can be influenced by a number of - * environment variables: - * - * - `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which - * messages should be prefixed by the program name and PID of the - * application. - * - * - `G_MESSAGES_DEBUG`: A space-separated list of log domains for - * which debug and informational messages are printed. By default - * these messages are not printed. - * - * stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, - * %G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for - * the rest, unless stderr was requested by - * g_log_writer_default_set_use_stderr(). - * - * This has no effect if structured logging is enabled; see - * [Using Structured Logging][using-structured-logging]. - */ - - -/** - * g_log_remove_handler: - * @log_domain: the log domain - * @handler_id: the id of the handler, which was returned - * in g_log_set_handler() - * - * Removes the log handler. - * - * This has no effect if structured logging is enabled; see - * [Using Structured Logging][using-structured-logging]. - */ - - -/** - * g_log_set_always_fatal: - * @fatal_mask: the mask containing bits set for each level - * of error which is to be fatal - * - * Sets the message levels which are always fatal, in any log domain. - * When a message with any of these levels is logged the program terminates. - * You can only set the levels defined by GLib to be fatal. - * %G_LOG_LEVEL_ERROR is always fatal. - * - * You can also make some message levels fatal at runtime by setting - * the `G_DEBUG` environment variable (see - * [Running GLib Applications](glib-running.html)). - * - * Libraries should not call this function, as it affects all messages logged - * by a process, including those from other libraries. - * - * Structured log messages (using g_log_structured() and - * g_log_structured_array()) are fatal only if the default log writer is used; - * otherwise it is up to the writer function to determine which log messages - * are fatal. See [Using Structured Logging][using-structured-logging]. - * - * Returns: the old fatal mask - */ - - -/** - * g_log_set_default_handler: - * @log_func: the log handler function - * @user_data: data passed to the log handler - * - * Installs a default log handler which is used if no - * log handler has been set for the particular log domain - * and log level combination. By default, GLib uses - * g_log_default_handler() as default log handler. - * - * This has no effect if structured logging is enabled; see - * [Using Structured Logging][using-structured-logging]. - * - * Returns: the previous default log handler - * Since: 2.6 - */ - - -/** - * g_log_set_fatal_mask: - * @log_domain: the log domain - * @fatal_mask: the new fatal mask - * - * Sets the log levels which are fatal in the given domain. - * %G_LOG_LEVEL_ERROR is always fatal. - * - * This has no effect on structured log messages (using g_log_structured() or - * g_log_structured_array()). To change the fatal behaviour for specific log - * messages, programs must install a custom log writer function using - * g_log_set_writer_func(). See - * [Using Structured Logging][using-structured-logging]. - * - * This function is mostly intended to be used with - * %G_LOG_LEVEL_CRITICAL. You should typically not set - * %G_LOG_LEVEL_WARNING, %G_LOG_LEVEL_MESSAGE, %G_LOG_LEVEL_INFO or - * %G_LOG_LEVEL_DEBUG as fatal except inside of test programs. - * - * Returns: the old fatal mask for the log domain - */ - - -/** - * g_log_set_handler: - * @log_domain: (nullable): the log domain, or %NULL for the default "" - * application domain - * @log_levels: the log levels to apply the log handler for. - * To handle fatal and recursive messages as well, combine - * the log levels with the %G_LOG_FLAG_FATAL and - * %G_LOG_FLAG_RECURSION bit flags. - * @log_func: the log handler function - * @user_data: data passed to the log handler - * - * Sets the log handler for a domain and a set of log levels. - * - * To handle fatal and recursive messages the @log_levels parameter - * must be combined with the %G_LOG_FLAG_FATAL and %G_LOG_FLAG_RECURSION - * bit flags. - * - * Note that since the %G_LOG_LEVEL_ERROR log level is always fatal, if - * you want to set a handler for this log level you must combine it with - * %G_LOG_FLAG_FATAL. - * - * This has no effect if structured logging is enabled; see - * [Using Structured Logging][using-structured-logging]. - * - * Here is an example for adding a log handler for all warning messages - * in the default domain: - * - * |[<!-- language="C" --> - * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL - * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); - * ]| - * - * This example adds a log handler for all critical messages from GTK+: - * - * |[<!-- language="C" --> - * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL - * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); - * ]| - * - * This example adds a log handler for all messages from GLib: - * - * |[<!-- language="C" --> - * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL - * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); - * ]| - * - * Returns: the id of the new handler - */ - - -/** - * g_log_set_handler_full: (rename-to g_log_set_handler) - * @log_domain: (nullable): the log domain, or %NULL for the default "" - * application domain - * @log_levels: the log levels to apply the log handler for. - * To handle fatal and recursive messages as well, combine - * the log levels with the %G_LOG_FLAG_FATAL and - * %G_LOG_FLAG_RECURSION bit flags. - * @log_func: the log handler function - * @user_data: data passed to the log handler - * @destroy: destroy notify for @user_data, or %NULL - * - * Like g_log_set_handler(), but takes a destroy notify for the @user_data. - * - * This has no effect if structured logging is enabled; see - * [Using Structured Logging][using-structured-logging]. - * - * Returns: the id of the new handler - * Since: 2.46 - */ - - -/** - * g_log_set_writer_func: - * @func: log writer function, which must not be %NULL - * @user_data: (closure func): user data to pass to @func - * @user_data_free: (destroy func): function to free @user_data once it’s - * finished with, if non-%NULL - * - * Set a writer function which will be called to format and write out each log - * message. Each program should set a writer function, or the default writer - * (g_log_writer_default()) will be used. - * - * Libraries **must not** call this function — only programs are allowed to - * install a writer function, as there must be a single, central point where - * log messages are formatted and outputted. - * - * There can only be one writer function. It is an error to set more than one. - * - * Since: 2.50 - */ - - -/** - * g_log_structured: - * @log_domain: log domain, usually %G_LOG_DOMAIN - * @log_level: log level, either from #GLogLevelFlags, or a user-defined - * level - * @...: key-value pairs of structured data to add to the log entry, followed - * by the key "MESSAGE", followed by a printf()-style message format, - * followed by parameters to insert in the format string - * - * Log a message with structured data. - * - * The message will be passed through to the log writer set by the application - * using g_log_set_writer_func(). If the message is fatal (i.e. its log level - * is %G_LOG_LEVEL_ERROR), the program will be aborted by calling - * G_BREAKPOINT() at the end of this function. If the log writer returns - * %G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried. - * See the documentation for #GLogWriterFunc for information on chaining - * writers. - * - * The structured data is provided as key–value pairs, where keys are UTF-8 - * strings, and values are arbitrary pointers — typically pointing to UTF-8 - * strings, but that is not a requirement. To pass binary (non-nul-terminated) - * structured data, use g_log_structured_array(). The keys for structured data - * should follow the [systemd journal - * fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html) - * specification. It is suggested that custom keys are namespaced according to - * the code which sets them. For example, custom keys from GLib all have a - * `GLIB_` prefix. - * - * The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will - * be converted into a - * [`PRIORITY`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#PRIORITY=) - * field. The format string will have its placeholders substituted for the provided - * values and be converted into a - * [`MESSAGE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE=) - * field. - * - * Other fields you may commonly want to pass into this function: - * - * * [`MESSAGE_ID`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=) - * * [`CODE_FILE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=) - * * [`CODE_LINE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_LINE=) - * * [`CODE_FUNC`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FUNC=) - * * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=) - * - * Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by - * the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), - * g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including - * `glib.h`. - * - * For example: - * - * |[<!-- language="C" --> - * g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, - * "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", - * "MY_APPLICATION_CUSTOM_FIELD", "some debug string", - * "MESSAGE", "This is a debug message about pointer %p and integer %u.", - * some_pointer, some_integer); - * ]| - * - * Note that each `MESSAGE_ID` must be [uniquely and randomly - * generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=). - * If adding a `MESSAGE_ID`, consider shipping a [message - * catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with - * your software. - * - * To pass a user data pointer to the log writer function which is specific to - * this logging call, you must use g_log_structured_array() and pass the pointer - * as a field with #GLogField.length set to zero, otherwise it will be - * interpreted as a string. - * - * For example: - * - * |[<!-- language="C" --> - * const GLogField fields[] = { - * { "MESSAGE", "This is a debug message.", -1 }, - * { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 }, - * { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 }, - * { "MY_APPLICATION_STATE", state_object, 0 }, - * }; - * g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields)); - * ]| - * - * Note also that, even if no other structured fields are specified, there - * must always be a `MESSAGE` key before the format string. The `MESSAGE`-format - * pair has to be the last of the key-value pairs, and `MESSAGE` is the only - * field for which printf()-style formatting is supported. - * - * The default writer function for `stdout` and `stderr` will automatically - * append a new-line character after the message, so you should not add one - * manually to the format string. - * - * Since: 2.50 - */ - - -/** - * g_log_structured_array: - * @log_level: log level, either from #GLogLevelFlags, or a user-defined - * level - * @fields: (array length=n_fields): key–value pairs of structured data to add - * to the log message - * @n_fields: number of elements in the @fields array - * - * Log a message with structured data. The message will be passed through to the - * log writer set by the application using g_log_set_writer_func(). If the - * message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will - * be aborted at the end of this function. - * - * See g_log_structured() for more documentation. - * - * This assumes that @log_level is already present in @fields (typically as the - * `PRIORITY` field). - * - * Since: 2.50 - */ - - -/** - * g_log_variant: - * @log_domain: (nullable): log domain, usually %G_LOG_DOMAIN - * @log_level: log level, either from #GLogLevelFlags, or a user-defined - * level - * @fields: a dictionary (#GVariant of the type %G_VARIANT_TYPE_VARDICT) - * containing the key-value pairs of message data. - * - * Log a message with structured data, accepting the data within a #GVariant. This - * version is especially useful for use in other languages, via introspection. - * - * The only mandatory item in the @fields dictionary is the "MESSAGE" which must - * contain the text shown to the user. - * - * The values in the @fields dictionary are likely to be of type String - * (#G_VARIANT_TYPE_STRING). Array of bytes (#G_VARIANT_TYPE_BYTESTRING) is also - * supported. In this case the message is handled as binary and will be forwarded - * to the log writer as such. The size of the array should not be higher than - * %G_MAXSSIZE. Otherwise it will be truncated to this size. For other types - * g_variant_print() will be used to convert the value into a string. - * - * For more details on its usage and about the parameters, see g_log_structured(). - * - * Since: 2.50 - */ - - -/** - * g_log_writer_default: - * @log_level: log level, either from #GLogLevelFlags, or a user-defined - * level - * @fields: (array length=n_fields): key–value pairs of structured data forming - * the log message - * @n_fields: number of elements in the @fields array - * @user_data: user data passed to g_log_set_writer_func() - * - * Format a structured log message and output it to the default log destination - * for the platform. On Linux, this is typically the systemd journal, falling - * back to `stdout` or `stderr` if running from the terminal or if output is - * being redirected to a file. - * - * Support for other platform-specific logging mechanisms may be added in - * future. Distributors of GLib may modify this function to impose their own - * (documented) platform-specific log writing policies. - * - * This is suitable for use as a #GLogWriterFunc, and is the default writer used - * if no other is set using g_log_set_writer_func(). - * - * As with g_log_default_handler(), this function drops debug and informational - * messages unless their log domain (or `all`) is listed in the space-separated - * `G_MESSAGES_DEBUG` environment variable. - * - * g_log_writer_default() uses the mask set by g_log_set_always_fatal() to - * determine which messages are fatal. When using a custom writer func instead it is - * up to the writer function to determine which log messages are fatal. - * - * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise - * Since: 2.50 - */ - - -/** - * g_log_writer_default_set_use_stderr: - * @use_stderr: If %TRUE, use `stderr` for log messages that would - * normally have appeared on `stdout` - * - * Configure whether the built-in log functions - * (g_log_default_handler() for the old-style API, and both - * g_log_writer_default() and g_log_writer_standard_streams() for the - * structured API) will output all log messages to `stderr`. - * - * By default, log messages of levels %G_LOG_LEVEL_INFO and - * %G_LOG_LEVEL_DEBUG are sent to `stdout`, and other log messages are - * sent to `stderr`. This is problematic for applications that intend - * to reserve `stdout` for structured output such as JSON or XML. - * - * This function sets global state. It is not thread-aware, and should be - * called at the very start of a program, before creating any other threads - * or creating objects that could create worker threads of their own. - * - * Since: 2.68 - */ - - -/** - * g_log_writer_default_would_drop: - * @log_domain: (nullable): log domain - * @log_level: log level, either from #GLogLevelFlags, or a user-defined - * level - * - * Check whether g_log_writer_default() and g_log_default_handler() would - * ignore a message with the given domain and level. - * - * As with g_log_default_handler(), this function drops debug and informational - * messages unless their log domain (or `all`) is listed in the space-separated - * `G_MESSAGES_DEBUG` environment variable. - * - * This can be used when implementing log writers with the same filtering - * behaviour as the default, but a different destination or output format: - * - * |[<!-- language="C" --> - * if (g_log_writer_default_would_drop (log_level, log_domain)) - * return G_LOG_WRITER_HANDLED; - * ]| - * - * or to skip an expensive computation if it is only needed for a debugging - * message, and `G_MESSAGES_DEBUG` is not set: - * - * |[<!-- language="C" --> - * if (!g_log_writer_default_would_drop (G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN)) - * { - * gchar *result = expensive_computation (my_object); - * - * g_debug ("my_object result: %s", result); - * g_free (result); - * } - * ]| - * - * Returns: %TRUE if the log message would be dropped by GLib's - * default log handlers - * Since: 2.68 - */ - - -/** - * g_log_writer_format_fields: - * @log_level: log level, either from #GLogLevelFlags, or a user-defined - * level - * @fields: (array length=n_fields): key–value pairs of structured data forming - * the log message - * @n_fields: number of elements in the @fields array - * @use_color: %TRUE to use ANSI color escape sequences when formatting the - * message, %FALSE to not - * - * Format a structured log message as a string suitable for outputting to the - * terminal (or elsewhere). This will include the values of all fields it knows - * how to interpret, which includes `MESSAGE` and `GLIB_DOMAIN` (see the - * documentation for g_log_structured()). It does not include values from - * unknown fields. - * - * The returned string does **not** have a trailing new-line character. It is - * encoded in the character set of the current locale, which is not necessarily - * UTF-8. - * - * Returns: (transfer full): string containing the formatted log message, in - * the character set of the current locale - * Since: 2.50 - */ - - -/** - * g_log_writer_is_journald: - * @output_fd: output file descriptor to check - * - * Check whether the given @output_fd file descriptor is a connection to the - * systemd journal, or something else (like a log file or `stdout` or - * `stderr`). - * - * Invalid file descriptors are accepted and return %FALSE, which allows for - * the following construct without needing any additional error handling: - * |[<!-- language="C" --> - * is_journald = g_log_writer_is_journald (fileno (stderr)); - * ]| - * - * Returns: %TRUE if @output_fd points to the journal, %FALSE otherwise - * Since: 2.50 - */ - - -/** - * g_log_writer_journald: - * @log_level: log level, either from #GLogLevelFlags, or a user-defined - * level - * @fields: (array length=n_fields): key–value pairs of structured data forming - * the log message - * @n_fields: number of elements in the @fields array - * @user_data: user data passed to g_log_set_writer_func() - * - * Format a structured log message and send it to the systemd journal as a set - * of key–value pairs. All fields are sent to the journal, but if a field has - * length zero (indicating program-specific data) then only its key will be - * sent. - * - * This is suitable for use as a #GLogWriterFunc. - * - * If GLib has been compiled without systemd support, this function is still - * defined, but will always return %G_LOG_WRITER_UNHANDLED. - * - * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise - * Since: 2.50 - */ - - -/** - * g_log_writer_standard_streams: - * @log_level: log level, either from #GLogLevelFlags, or a user-defined - * level - * @fields: (array length=n_fields): key–value pairs of structured data forming - * the log message - * @n_fields: number of elements in the @fields array - * @user_data: user data passed to g_log_set_writer_func() - * - * Format a structured log message and print it to either `stdout` or `stderr`, - * depending on its log level. %G_LOG_LEVEL_INFO and %G_LOG_LEVEL_DEBUG messages - * are sent to `stdout`, or to `stderr` if requested by - * g_log_writer_default_set_use_stderr(); - * all other log levels are sent to `stderr`. Only fields - * which are understood by this function are included in the formatted string - * which is printed. - * - * If the output stream supports ANSI color escape sequences, they will be used - * in the output. - * - * A trailing new-line character is added to the log message when it is printed. - * - * This is suitable for use as a #GLogWriterFunc. - * - * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise - * Since: 2.50 - */ - - -/** - * g_log_writer_supports_color: - * @output_fd: output file descriptor to check - * - * Check whether the given @output_fd file descriptor supports ANSI color - * escape sequences. If so, they can safely be used when formatting log - * messages. - * - * Returns: %TRUE if ANSI color escapes are supported, %FALSE otherwise - * Since: 2.50 - */ - - -/** - * g_logv: - * @log_domain: (nullable): the log domain, or %NULL for the default "" - * application domain - * @log_level: the log level - * @format: the message format. See the printf() documentation - * @args: the parameters to insert into the format string - * - * Logs an error or debugging message. - * - * If the log level has been set as fatal, G_BREAKPOINT() is called - * to terminate the program. See the documentation for G_BREAKPOINT() for - * details of the debugging options this provides. - * - * 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][using-structured-logging] this will - * output via the structured log writer function (see g_log_set_writer_func()). - */ - - -/** - * g_lstat: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * @buf: a pointer to a stat struct, which will be filled with the file - * information - * - * A wrapper for the POSIX lstat() function. The lstat() function is - * like stat() except that in the case of symbolic links, it returns - * information about the symbolic link itself and not the file that it - * refers to. If the system does not support symbolic links g_lstat() - * is identical to g_stat(). - * - * See your C library manual for more details about lstat(). - * - * Returns: 0 if the information was successfully retrieved, - * -1 if an error occurred - * Since: 2.6 - */ - - -/** - * g_main_context_acquire: - * @context: a #GMainContext - * - * Tries to become the owner of the specified context. - * If some other thread is the owner of the context, - * returns %FALSE immediately. Ownership is properly - * recursive: the owner can require ownership again - * and will release ownership when g_main_context_release() - * is called as many times as g_main_context_acquire(). - * - * You must be the owner of a context before you - * can call g_main_context_prepare(), g_main_context_query(), - * g_main_context_check(), g_main_context_dispatch(). - * - * Returns: %TRUE if the operation succeeded, and - * this thread is now the owner of @context. - */ - - -/** - * g_main_context_add_poll: - * @context: (nullable): a #GMainContext (or %NULL for the default context) - * @fd: a #GPollFD structure holding information about a file - * descriptor to watch. - * @priority: the priority for this file descriptor which should be - * the same as the priority used for g_source_attach() to ensure that the - * file descriptor is polled whenever the results may be needed. - * - * Adds a file descriptor to the set of file descriptors polled for - * this context. This will very seldom be used directly. Instead - * a typical event source will use g_source_add_unix_fd() instead. - */ - - -/** - * g_main_context_check: - * @context: a #GMainContext - * @max_priority: the maximum numerical priority of sources to check - * @fds: (array length=n_fds): array of #GPollFD's that was passed to - * the last call to g_main_context_query() - * @n_fds: return value of g_main_context_query() - * - * Passes the results of polling back to the main loop. You should be - * careful to pass @fds and its length @n_fds as received from - * g_main_context_query(), as this functions relies on assumptions - * on how @fds is filled. - * - * You must have successfully acquired the context with - * g_main_context_acquire() before you may call this function. - * - * Returns: %TRUE if some sources are ready to be dispatched. - */ - - -/** - * g_main_context_default: - * - * Returns the global default main context. This is the main context - * used for main loop functions when a main loop is not explicitly - * specified, and corresponds to the "main" main loop. See also - * g_main_context_get_thread_default(). - * - * Returns: (transfer none): the global default main context. - */ - - -/** - * g_main_context_dispatch: - * @context: a #GMainContext - * - * Dispatches all pending sources. - * - * You must have successfully acquired the context with - * g_main_context_acquire() before you may call this function. - */ - - -/** - * g_main_context_find_source_by_funcs_user_data: - * @context: (nullable): a #GMainContext (if %NULL, the default context will be used). - * @funcs: the @source_funcs passed to g_source_new(). - * @user_data: the user data from the callback. - * - * Finds a source with the given source functions and user data. If - * multiple sources exist with the same source function and user data, - * the first one found will be returned. - * - * Returns: (transfer none): the source, if one was found, otherwise %NULL - */ - - -/** - * g_main_context_find_source_by_id: - * @context: (nullable): a #GMainContext (if %NULL, the default context will be used) - * @source_id: the source ID, as returned by g_source_get_id(). - * - * Finds a #GSource given a pair of context and ID. - * - * It is a programmer error to attempt to look up a non-existent source. - * - * More specifically: source IDs can be reissued after a source has been - * destroyed and therefore it is never valid to use this function with a - * source ID which may have already been removed. An example is when - * scheduling an idle to run in another thread with g_idle_add(): the - * idle may already have run and been removed by the time this function - * is called on its (now invalid) source ID. This source ID may have - * been reissued, leading to the operation being performed against the - * wrong source. - * - * Returns: (transfer none): the #GSource - */ - - -/** - * g_main_context_find_source_by_user_data: - * @context: a #GMainContext - * @user_data: the user_data for the callback. - * - * Finds a source with the given user data for the callback. If - * multiple sources exist with the same user data, the first - * one found will be returned. - * - * Returns: (transfer none): the source, if one was found, otherwise %NULL - */ - - -/** - * g_main_context_get_poll_func: - * @context: a #GMainContext - * - * Gets the poll function set by g_main_context_set_poll_func(). - * - * Returns: the poll function - */ - - -/** - * g_main_context_get_thread_default: - * - * Gets the thread-default #GMainContext for this thread. Asynchronous - * operations that want to be able to be run in contexts other than - * the default one should call this method or - * g_main_context_ref_thread_default() to get a #GMainContext to add - * their #GSources to. (Note that even in single-threaded - * programs applications may sometimes want to temporarily push a - * non-default context, so it is not safe to assume that this will - * always return %NULL if you are running in the default thread.) - * - * If you need to hold a reference on the context, use - * g_main_context_ref_thread_default() instead. - * - * Returns: (transfer none) (nullable): the thread-default #GMainContext, or - * %NULL if the thread-default context is the global default context. - * Since: 2.22 - */ - - -/** - * g_main_context_invoke: - * @context: (nullable): a #GMainContext, or %NULL - * @function: function to call - * @data: data to pass to @function - * - * Invokes a function in such a way that @context is owned during the - * invocation of @function. - * - * If @context is %NULL then the global default main context — as - * returned by g_main_context_default() — is used. - * - * If @context is owned by the current thread, @function is called - * directly. Otherwise, if @context is the thread-default main context - * of the current thread and g_main_context_acquire() succeeds, then - * @function is called and g_main_context_release() is called - * afterwards. - * - * In any other case, an idle source is created to call @function and - * that source is attached to @context (presumably to be run in another - * thread). The idle source is attached with %G_PRIORITY_DEFAULT - * priority. If you want a different priority, use - * g_main_context_invoke_full(). - * - * Note that, as with normal idle functions, @function should probably - * return %FALSE. If it returns %TRUE, it will be continuously run in a - * loop (and may prevent this call from returning). - * - * Since: 2.28 - */ - - -/** - * g_main_context_invoke_full: - * @context: (nullable): a #GMainContext, or %NULL - * @priority: the priority at which to run @function - * @function: function to call - * @data: data to pass to @function - * @notify: (nullable): a function to call when @data is no longer in use, or %NULL. - * - * Invokes a function in such a way that @context is owned during the - * invocation of @function. - * - * This function is the same as g_main_context_invoke() except that it - * lets you specify the priority in case @function ends up being - * scheduled as an idle and also lets you give a #GDestroyNotify for @data. - * - * @notify should not assume that it is called from any particular - * thread or with any particular context acquired. - * - * Since: 2.28 - */ - - -/** - * g_main_context_is_owner: - * @context: a #GMainContext - * - * Determines whether this thread holds the (recursive) - * ownership of this #GMainContext. This is useful to - * know before waiting on another thread that may be - * blocking to get ownership of @context. - * - * Returns: %TRUE if current thread is owner of @context. - * Since: 2.10 - */ - - -/** - * g_main_context_iteration: - * @context: (nullable): a #GMainContext (if %NULL, the default context will be used) - * @may_block: whether the call may block. - * - * Runs a single iteration for the given main loop. This involves - * checking to see if any event sources are ready to be processed, - * then if no events sources are ready and @may_block is %TRUE, waiting - * for a source to become ready, then dispatching the highest priority - * events sources that are ready. Otherwise, if @may_block is %FALSE - * sources are not waited to become ready, only those highest priority - * events sources will be dispatched (if any), that are ready at this - * given moment without further waiting. - * - * Note that even when @may_block is %TRUE, it is still possible for - * g_main_context_iteration() to return %FALSE, since the wait may - * be interrupted for other reasons than an event source becoming ready. - * - * Returns: %TRUE if events were dispatched. - */ - - -/** - * g_main_context_new: - * - * Creates a new #GMainContext structure. - * - * Returns: the new #GMainContext - */ - - -/** - * g_main_context_pending: - * @context: (nullable): a #GMainContext (if %NULL, the default context will be used) - * - * Checks if any sources have pending events for the given context. - * - * Returns: %TRUE if events are pending. - */ - - -/** - * g_main_context_pop_thread_default: - * @context: (nullable): a #GMainContext object, or %NULL - * - * Pops @context off the thread-default context stack (verifying that - * it was on the top of the stack). - * - * Since: 2.22 - */ - - -/** - * g_main_context_prepare: - * @context: a #GMainContext - * @priority: (out) (optional): location to store priority of highest priority - * source already ready. - * - * Prepares to poll sources within a main loop. The resulting information - * for polling is determined by calling g_main_context_query (). - * - * You must have successfully acquired the context with - * g_main_context_acquire() before you may call this function. - * - * Returns: %TRUE if some source is ready to be dispatched - * prior to polling. - */ - - -/** - * g_main_context_push_thread_default: - * @context: (nullable): a #GMainContext, or %NULL for the global default context - * - * Acquires @context and sets it as the thread-default context for the - * current thread. This will cause certain asynchronous operations - * (such as most [gio][gio]-based I/O) which are - * started in this thread to run under @context and deliver their - * results to its main loop, rather than running under the global - * default context in the main thread. Note that calling this function - * changes the context returned by g_main_context_get_thread_default(), - * not the one returned by g_main_context_default(), so it does not affect - * the context used by functions like g_idle_add(). - * - * Normally you would call this function shortly after creating a new - * thread, passing it a #GMainContext which will be run by a - * #GMainLoop in that thread, to set a new default context for all - * async operations in that thread. In this case you may not need to - * ever call g_main_context_pop_thread_default(), assuming you want the - * new #GMainContext to be the default for the whole lifecycle of the - * thread. - * - * If you don't have control over how the new thread was created (e.g. - * in the new thread isn't newly created, or if the thread life - * cycle is managed by a #GThreadPool), it is always suggested to wrap - * the logic that needs to use the new #GMainContext inside a - * g_main_context_push_thread_default() / g_main_context_pop_thread_default() - * pair, otherwise threads that are re-used will end up never explicitly - * releasing the #GMainContext reference they hold. - * - * In some cases you may want to schedule a single operation in a - * non-default context, or temporarily use a non-default context in - * the main thread. In that case, you can wrap the call to the - * asynchronous operation inside a - * g_main_context_push_thread_default() / - * g_main_context_pop_thread_default() pair, but it is up to you to - * ensure that no other asynchronous operations accidentally get - * started while the non-default context is active. - * - * Beware that libraries that predate this function may not correctly - * handle being used from a thread with a thread-default context. Eg, - * see g_file_supports_thread_contexts(). - * - * Since: 2.22 - */ - - -/** - * g_main_context_query: - * @context: a #GMainContext - * @max_priority: maximum priority source to check - * @timeout_: (out): location to store timeout to be used in polling - * @fds: (out caller-allocates) (array length=n_fds): location to - * store #GPollFD records that need to be polled. - * @n_fds: (in): length of @fds. - * - * Determines information necessary to poll this main loop. You should - * be careful to pass the resulting @fds array and its length @n_fds - * as is when calling g_main_context_check(), as this function relies - * on assumptions made when the array is filled. - * - * You must have successfully acquired the context with - * g_main_context_acquire() before you may call this function. - * - * Returns: the number of records actually stored in @fds, - * or, if more than @n_fds records need to be stored, the number - * of records that need to be stored. - */ - - -/** - * g_main_context_ref: - * @context: a #GMainContext - * - * Increases the reference count on a #GMainContext object by one. - * - * Returns: the @context that was passed in (since 2.6) - */ - - -/** - * g_main_context_ref_thread_default: - * - * Gets the thread-default #GMainContext for this thread, as with - * g_main_context_get_thread_default(), but also adds a reference to - * it with g_main_context_ref(). In addition, unlike - * g_main_context_get_thread_default(), if the thread-default context - * is the global default context, this will return that #GMainContext - * (with a ref added to it) rather than returning %NULL. - * - * Returns: (transfer full): the thread-default #GMainContext. Unref - * with g_main_context_unref() when you are done with it. - * Since: 2.32 - */ - - -/** - * g_main_context_release: - * @context: a #GMainContext - * - * Releases ownership of a context previously acquired by this thread - * with g_main_context_acquire(). If the context was acquired multiple - * times, the ownership will be released only when g_main_context_release() - * is called as many times as it was acquired. - */ - - -/** - * g_main_context_remove_poll: - * @context: a #GMainContext - * @fd: a #GPollFD descriptor previously added with g_main_context_add_poll() - * - * Removes file descriptor from the set of file descriptors to be - * polled for a particular context. - */ - - -/** - * g_main_context_set_poll_func: - * @context: a #GMainContext - * @func: the function to call to poll all file descriptors - * - * Sets the function to use to handle polling of file descriptors. It - * will be used instead of the poll() system call - * (or GLib's replacement function, which is used where - * poll() isn't available). - * - * This function could possibly be used to integrate the GLib event - * loop with an external event loop. - */ - - -/** - * g_main_context_unref: - * @context: a #GMainContext - * - * Decreases the reference count on a #GMainContext object by one. If - * the result is zero, free the context and free all associated memory. - */ - - -/** - * g_main_context_wait: - * @context: a #GMainContext - * @cond: a condition variable - * @mutex: a mutex, currently held - * - * Tries to become the owner of the specified context, - * as with g_main_context_acquire(). But if another thread - * is the owner, atomically drop @mutex and wait on @cond until - * that owner releases ownership or until @cond is signaled, then - * try again (once) to become the owner. - * - * Returns: %TRUE if the operation succeeded, and - * this thread is now the owner of @context. - * Deprecated: 2.58: Use g_main_context_is_owner() and separate locking instead. - */ - - -/** - * g_main_context_wakeup: - * @context: a #GMainContext - * - * If @context is currently blocking in g_main_context_iteration() - * waiting for a source to become ready, cause it to stop blocking - * and return. Otherwise, cause the next invocation of - * g_main_context_iteration() to return without blocking. - * - * This API is useful for low-level control over #GMainContext; for - * example, integrating it with main loop implementations such as - * #GMainLoop. - * - * Another related use for this function is when implementing a main - * loop with a termination condition, computed from multiple threads: - * - * |[<!-- language="C" --> - * #define NUM_TASKS 10 - * static gint tasks_remaining = NUM_TASKS; // (atomic) - * ... - * - * while (g_atomic_int_get (&tasks_remaining) != 0) - * g_main_context_iteration (NULL, TRUE); - * ]| - * - * Then in a thread: - * |[<!-- language="C" --> - * perform_work(); - * - * if (g_atomic_int_dec_and_test (&tasks_remaining)) - * g_main_context_wakeup (NULL); - * ]| - */ - - -/** - * g_main_current_source: - * - * Returns the currently firing source for this thread. - * - * Returns: (transfer none) (nullable): The currently firing source or %NULL. - * Since: 2.12 - */ - - -/** - * g_main_depth: - * - * Returns the depth of the stack of calls to - * g_main_context_dispatch() on any #GMainContext in the current thread. - * That is, when called from the toplevel, it gives 0. When - * called from within a callback from g_main_context_iteration() - * (or g_main_loop_run(), etc.) it returns 1. When called from within - * a callback to a recursive call to g_main_context_iteration(), - * it returns 2. And so forth. - * - * This function is useful in a situation like the following: - * Imagine an extremely simple "garbage collected" system. - * - * |[<!-- language="C" --> - * static GList *free_list; - * - * gpointer - * allocate_memory (gsize size) - * { - * gpointer result = g_malloc (size); - * free_list = g_list_prepend (free_list, result); - * return result; - * } - * - * void - * free_allocated_memory (void) - * { - * GList *l; - * for (l = free_list; l; l = l->next); - * g_free (l->data); - * g_list_free (free_list); - * free_list = NULL; - * } - * - * [...] - * - * while (TRUE); - * { - * g_main_context_iteration (NULL, TRUE); - * free_allocated_memory(); - * } - * ]| - * - * This works from an application, however, if you want to do the same - * thing from a library, it gets more difficult, since you no longer - * control the main loop. You might think you can simply use an idle - * function to make the call to free_allocated_memory(), but that - * doesn't work, since the idle function could be called from a - * recursive callback. This can be fixed by using g_main_depth() - * - * |[<!-- language="C" --> - * gpointer - * allocate_memory (gsize size) - * { - * FreeListBlock *block = g_new (FreeListBlock, 1); - * block->mem = g_malloc (size); - * block->depth = g_main_depth (); - * free_list = g_list_prepend (free_list, block); - * return block->mem; - * } - * - * void - * free_allocated_memory (void) - * { - * GList *l; - * - * int depth = g_main_depth (); - * for (l = free_list; l; ); - * { - * GList *next = l->next; - * FreeListBlock *block = l->data; - * if (block->depth > depth) - * { - * g_free (block->mem); - * g_free (block); - * free_list = g_list_delete_link (free_list, l); - * } - * - * l = next; - * } - * } - * ]| - * - * There is a temptation to use g_main_depth() to solve - * problems with reentrancy. For instance, while waiting for data - * to be received from the network in response to a menu item, - * the menu item might be selected again. It might seem that - * one could make the menu item's callback return immediately - * and do nothing if g_main_depth() returns a value greater than 1. - * However, this should be avoided since the user then sees selecting - * the menu item do nothing. Furthermore, you'll find yourself adding - * these checks all over your code, since there are doubtless many, - * many things that the user could do. Instead, you can use the - * following techniques: - * - * 1. Use gtk_widget_set_sensitive() or modal dialogs to prevent - * the user from interacting with elements while the main - * loop is recursing. - * - * 2. Avoid main loop recursion in situations where you can't handle - * arbitrary callbacks. Instead, structure your code so that you - * simply return to the main loop and then get called again when - * there is more work to do. - * - * Returns: The main loop recursion level in the current thread - */ - - -/** - * g_main_loop_get_context: - * @loop: a #GMainLoop. - * - * Returns the #GMainContext of @loop. - * - * Returns: (transfer none): the #GMainContext of @loop - */ - - -/** - * g_main_loop_is_running: - * @loop: a #GMainLoop. - * - * Checks to see if the main loop is currently being run via g_main_loop_run(). - * - * Returns: %TRUE if the mainloop is currently being run. - */ - - -/** - * g_main_loop_new: - * @context: (nullable): a #GMainContext (if %NULL, the default context will be used). - * @is_running: set to %TRUE to indicate that the loop is running. This - * is not very important since calling g_main_loop_run() will set this to - * %TRUE anyway. - * - * Creates a new #GMainLoop structure. - * - * Returns: a new #GMainLoop. - */ - - -/** - * g_main_loop_quit: - * @loop: a #GMainLoop - * - * Stops a #GMainLoop from running. Any calls to g_main_loop_run() - * for the loop will return. - * - * Note that sources that have already been dispatched when - * g_main_loop_quit() is called will still be executed. - */ - - -/** - * g_main_loop_ref: - * @loop: a #GMainLoop - * - * Increases the reference count on a #GMainLoop object by one. - * - * Returns: @loop - */ - - -/** - * g_main_loop_run: - * @loop: a #GMainLoop - * - * Runs a main loop until g_main_loop_quit() is called on the loop. - * If this is called for the thread of the loop's #GMainContext, - * it will process events from the loop, otherwise it will - * simply wait. - */ - - -/** - * g_main_loop_unref: - * @loop: a #GMainLoop - * - * Decreases the reference count on a #GMainLoop object by one. If - * the result is zero, free the loop and free all associated memory. - */ - - -/** - * g_malloc: - * @n_bytes: the number of bytes to allocate - * - * Allocates @n_bytes bytes of memory. - * If @n_bytes is 0 it returns %NULL. - * - * Returns: a pointer to the allocated memory - */ - - -/** - * g_malloc0: - * @n_bytes: the number of bytes to allocate - * - * Allocates @n_bytes bytes of memory, initialized to 0's. - * If @n_bytes is 0 it returns %NULL. - * - * Returns: a pointer to the allocated memory - */ - - -/** - * g_malloc0_n: - * @n_blocks: the number of blocks to allocate - * @n_block_bytes: the size of each block in bytes - * - * This function is similar to g_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, - * but care is taken to detect possible overflow during multiplication. - * - * Since: 2.24 - * Returns: a pointer to the allocated memory - */ - - -/** - * g_malloc_n: - * @n_blocks: the number of blocks to allocate - * @n_block_bytes: the size of each block in bytes - * - * This function is similar to g_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, - * but care is taken to detect possible overflow during multiplication. - * - * Since: 2.24 - * Returns: a pointer to the allocated memory - */ - - -/** - * g_mapped_file_free: - * @file: a #GMappedFile - * - * This call existed before #GMappedFile had refcounting and is currently - * exactly the same as g_mapped_file_unref(). - * - * Since: 2.8 - * Deprecated: 2.22: Use g_mapped_file_unref() instead. - */ - - -/** - * g_mapped_file_get_bytes: - * @file: a #GMappedFile - * - * Creates a new #GBytes which references the data mapped from @file. - * The mapped contents of the file must not be modified after creating this - * bytes object, because a #GBytes should be immutable. - * - * Returns: (transfer full): A newly allocated #GBytes referencing data - * from @file - * Since: 2.34 - */ - - -/** - * g_mapped_file_get_contents: - * @file: a #GMappedFile - * - * Returns the contents of a #GMappedFile. - * - * Note that the contents may not be zero-terminated, - * even if the #GMappedFile is backed by a text file. - * - * If the file is empty then %NULL is returned. - * - * Returns: the contents of @file, or %NULL. - * Since: 2.8 - */ - - -/** - * g_mapped_file_get_length: - * @file: a #GMappedFile - * - * Returns the length of the contents of a #GMappedFile. - * - * Returns: the length of the contents of @file. - * Since: 2.8 - */ - - -/** - * g_mapped_file_new: - * @filename: (type filename): The path of the file to load, in the GLib - * filename encoding - * @writable: whether the mapping should be writable - * @error: return location for a #GError, or %NULL - * - * Maps a file into memory. On UNIX, this is using the mmap() function. - * - * If @writable is %TRUE, the mapped buffer may be modified, otherwise - * it is an error to modify the mapped buffer. Modifications to the buffer - * are not visible to other processes mapping the same file, and are not - * written back to the file. - * - * Note that modifications of the underlying file might affect the contents - * of the #GMappedFile. Therefore, mapping should only be used if the file - * will not be modified, or if all modifications of the file are done - * atomically (e.g. using g_file_set_contents()). - * - * If @filename is the name of an empty, regular file, the function - * will successfully return an empty #GMappedFile. In other cases of - * size 0 (e.g. device files such as /dev/null), @error will be set - * to the #GFileError value #G_FILE_ERROR_INVAL. - * - * Returns: a newly allocated #GMappedFile which must be unref'd - * with g_mapped_file_unref(), or %NULL if the mapping failed. - * Since: 2.8 - */ - - -/** - * g_mapped_file_new_from_fd: - * @fd: The file descriptor of the file to load - * @writable: whether the mapping should be writable - * @error: return location for a #GError, or %NULL - * - * Maps a file into memory. On UNIX, this is using the mmap() function. - * - * If @writable is %TRUE, the mapped buffer may be modified, otherwise - * it is an error to modify the mapped buffer. Modifications to the buffer - * are not visible to other processes mapping the same file, and are not - * written back to the file. - * - * Note that modifications of the underlying file might affect the contents - * of the #GMappedFile. Therefore, mapping should only be used if the file - * will not be modified, or if all modifications of the file are done - * atomically (e.g. using g_file_set_contents()). - * - * Returns: a newly allocated #GMappedFile which must be unref'd - * with g_mapped_file_unref(), or %NULL if the mapping failed. - * Since: 2.32 - */ - - -/** - * g_mapped_file_ref: - * @file: a #GMappedFile - * - * Increments the reference count of @file by one. It is safe to call - * this function from any thread. - * - * Returns: the passed in #GMappedFile. - * Since: 2.22 - */ - - -/** - * g_mapped_file_unref: - * @file: a #GMappedFile - * - * Decrements the reference count of @file by one. If the reference count - * drops to 0, unmaps the buffer of @file and frees it. - * - * It is safe to call this function from any thread. - * - * Since 2.22 - */ - - -/** - * g_markup_collect_attributes: - * @element_name: the current tag name - * @attribute_names: the attribute names - * @attribute_values: the attribute values - * @error: a pointer to a #GError or %NULL - * @first_type: the #GMarkupCollectType of the first attribute - * @first_attr: the name of the first attribute - * @...: a pointer to the storage location of the first attribute - * (or %NULL), followed by more types names and pointers, ending - * with %G_MARKUP_COLLECT_INVALID - * - * Collects the attributes of the element from the data passed to the - * #GMarkupParser start_element function, dealing with common error - * conditions and supporting boolean values. - * - * This utility function is not required to write a parser but can save - * a lot of typing. - * - * The @element_name, @attribute_names, @attribute_values and @error - * parameters passed to the start_element callback should be passed - * unmodified to this function. - * - * Following these arguments is a list of "supported" attributes to collect. - * It is an error to specify multiple attributes with the same name. If any - * attribute not in the list appears in the @attribute_names array then an - * unknown attribute error will result. - * - * The #GMarkupCollectType field allows specifying the type of collection - * to perform and if a given attribute must appear or is optional. - * - * The attribute name is simply the name of the attribute to collect. - * - * The pointer should be of the appropriate type (see the descriptions - * under #GMarkupCollectType) and may be %NULL in case a particular - * attribute is to be allowed but ignored. - * - * This function deals with issuing errors for missing attributes - * (of type %G_MARKUP_ERROR_MISSING_ATTRIBUTE), unknown attributes - * (of type %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE) and duplicate - * attributes (of type %G_MARKUP_ERROR_INVALID_CONTENT) as well - * as parse errors for boolean-valued attributes (again of type - * %G_MARKUP_ERROR_INVALID_CONTENT). In all of these cases %FALSE - * will be returned and @error will be set as appropriate. - * - * Returns: %TRUE if successful - * Since: 2.16 - */ - - -/** - * g_markup_escape_text: - * @text: some valid UTF-8 text - * @length: length of @text in bytes, or -1 if the text is nul-terminated - * - * Escapes text so that the markup parser will parse it verbatim. - * Less than, greater than, ampersand, etc. are replaced with the - * corresponding entities. This function would typically be used - * when writing out a file to be parsed with the markup parser. - * - * Note that this function doesn't protect whitespace and line endings - * from being processed according to the XML rules for normalization - * of line endings and attribute values. - * - * Note also that this function will produce character references in - * the range of  ...  for all control sequences - * except for tabstop, newline and carriage return. The character - * references in this range are not valid XML 1.0, but they are - * valid XML 1.1 and will be accepted by the GMarkup parser. - * - * Returns: a newly allocated string with the escaped text - */ - - -/** - * g_markup_parse_context_end_parse: - * @context: a #GMarkupParseContext - * @error: return location for a #GError - * - * Signals to the #GMarkupParseContext that all data has been - * fed into the parse context with g_markup_parse_context_parse(). - * - * This function reports an error if the document isn't complete, - * for example if elements are still open. - * - * Returns: %TRUE on success, %FALSE if an error was set - */ - - -/** - * g_markup_parse_context_free: - * @context: a #GMarkupParseContext - * - * Frees a #GMarkupParseContext. - * - * This function can't be called from inside one of the - * #GMarkupParser functions or while a subparser is pushed. - */ - - -/** - * g_markup_parse_context_get_element: - * @context: a #GMarkupParseContext - * - * Retrieves the name of the currently open element. - * - * If called from the start_element or end_element handlers this will - * give the element_name as passed to those functions. For the parent - * elements, see g_markup_parse_context_get_element_stack(). - * - * Returns: the name of the currently open element, or %NULL - * Since: 2.2 - */ - - -/** - * g_markup_parse_context_get_element_stack: - * @context: a #GMarkupParseContext - * - * Retrieves the element stack from the internal state of the parser. - * - * The returned #GSList is a list of strings where the first item is - * the currently open tag (as would be returned by - * g_markup_parse_context_get_element()) and the next item is its - * immediate parent. - * - * This function is intended to be used in the start_element and - * end_element handlers where g_markup_parse_context_get_element() - * would merely return the name of the element that is being - * processed. - * - * Returns: the element stack, which must not be modified - * Since: 2.16 - */ - - -/** - * g_markup_parse_context_get_position: - * @context: a #GMarkupParseContext - * @line_number: (out) (optional): return location for a line number, or %NULL - * @char_number: (out) (optional): return location for a char-on-line number, or %NULL - * - * Retrieves the current line number and the number of the character on - * that line. Intended for use in error messages; there are no strict - * semantics for what constitutes the "current" line number other than - * "the best number we could come up with for error messages." - */ - - -/** - * g_markup_parse_context_get_user_data: - * @context: a #GMarkupParseContext - * - * Returns the user_data associated with @context. - * - * This will either be the user_data that was provided to - * g_markup_parse_context_new() or to the most recent call - * of g_markup_parse_context_push(). - * - * Returns: the provided user_data. The returned data belongs to - * the markup context and will be freed when - * g_markup_parse_context_free() is called. - * Since: 2.18 - */ - - -/** - * g_markup_parse_context_new: - * @parser: a #GMarkupParser - * @flags: one or more #GMarkupParseFlags - * @user_data: user data to pass to #GMarkupParser functions - * @user_data_dnotify: user data destroy notifier called when - * the parse context is freed - * - * Creates a new parse context. A parse context is used to parse - * marked-up documents. You can feed any number of documents into - * a context, as long as no errors occur; once an error occurs, - * the parse context can't continue to parse text (you have to - * free it and create a new parse context). - * - * Returns: a new #GMarkupParseContext - */ - - -/** - * g_markup_parse_context_parse: - * @context: a #GMarkupParseContext - * @text: chunk of text to parse - * @text_len: length of @text in bytes - * @error: return location for a #GError - * - * Feed some data to the #GMarkupParseContext. - * - * The data need not be valid UTF-8; an error will be signaled if - * it's invalid. The data need not be an entire document; you can - * feed a document into the parser incrementally, via multiple calls - * to this function. Typically, as you receive data from a network - * connection or file, you feed each received chunk of data into this - * function, aborting the process if an error occurs. Once an error - * is reported, no further data may be fed to the #GMarkupParseContext; - * all errors are fatal. - * - * Returns: %FALSE if an error occurred, %TRUE on success - */ - - -/** - * g_markup_parse_context_pop: - * @context: a #GMarkupParseContext - * - * Completes the process of a temporary sub-parser redirection. - * - * This function exists to collect the user_data allocated by a - * matching call to g_markup_parse_context_push(). It must be called - * in the end_element handler corresponding to the start_element - * handler during which g_markup_parse_context_push() was called. - * You must not call this function from the error callback -- the - * @user_data is provided directly to the callback in that case. - * - * This function is not intended to be directly called by users - * interested in invoking subparsers. Instead, it is intended to - * be used by the subparsers themselves to implement a higher-level - * interface. - * - * Returns: the user data passed to g_markup_parse_context_push() - * Since: 2.18 - */ - - -/** - * g_markup_parse_context_push: - * @context: a #GMarkupParseContext - * @parser: a #GMarkupParser - * @user_data: user data to pass to #GMarkupParser functions - * - * Temporarily redirects markup data to a sub-parser. - * - * This function may only be called from the start_element handler of - * a #GMarkupParser. It must be matched with a corresponding call to - * g_markup_parse_context_pop() in the matching end_element handler - * (except in the case that the parser aborts due to an error). - * - * All tags, text and other data between the matching tags is - * redirected to the subparser given by @parser. @user_data is used - * as the user_data for that parser. @user_data is also passed to the - * error callback in the event that an error occurs. This includes - * errors that occur in subparsers of the subparser. - * - * The end tag matching the start tag for which this call was made is - * handled by the previous parser (which is given its own user_data) - * which is why g_markup_parse_context_pop() is provided to allow "one - * last access" to the @user_data provided to this function. In the - * case of error, the @user_data provided here is passed directly to - * the error callback of the subparser and g_markup_parse_context_pop() - * should not be called. In either case, if @user_data was allocated - * then it ought to be freed from both of these locations. - * - * This function is not intended to be directly called by users - * interested in invoking subparsers. Instead, it is intended to be - * used by the subparsers themselves to implement a higher-level - * interface. - * - * As an example, see the following implementation of a simple - * parser that counts the number of tags encountered. - * - * |[<!-- language="C" --> - * typedef struct - * { - * gint tag_count; - * } CounterData; - * - * static void - * counter_start_element (GMarkupParseContext *context, - * const gchar *element_name, - * const gchar **attribute_names, - * const gchar **attribute_values, - * gpointer user_data, - * GError **error) - * { - * CounterData *data = user_data; - * - * data->tag_count++; - * } - * - * static void - * counter_error (GMarkupParseContext *context, - * GError *error, - * gpointer user_data) - * { - * CounterData *data = user_data; - * - * g_slice_free (CounterData, data); - * } - * - * static GMarkupParser counter_subparser = - * { - * counter_start_element, - * NULL, - * NULL, - * NULL, - * counter_error - * }; - * ]| - * - * In order to allow this parser to be easily used as a subparser, the - * following interface is provided: - * - * |[<!-- language="C" --> - * void - * start_counting (GMarkupParseContext *context) - * { - * CounterData *data = g_slice_new (CounterData); - * - * data->tag_count = 0; - * g_markup_parse_context_push (context, &counter_subparser, data); - * } - * - * gint - * end_counting (GMarkupParseContext *context) - * { - * CounterData *data = g_markup_parse_context_pop (context); - * int result; - * - * result = data->tag_count; - * g_slice_free (CounterData, data); - * - * return result; - * } - * ]| - * - * The subparser would then be used as follows: - * - * |[<!-- language="C" --> - * static void start_element (context, element_name, ...) - * { - * if (strcmp (element_name, "count-these") == 0) - * start_counting (context); - * - * // else, handle other tags... - * } - * - * static void end_element (context, element_name, ...) - * { - * if (strcmp (element_name, "count-these") == 0) - * g_print ("Counted %d tags\n", end_counting (context)); - * - * // else, handle other tags... - * } - * ]| - * - * Since: 2.18 - */ - - -/** - * g_markup_parse_context_ref: - * @context: a #GMarkupParseContext - * - * Increases the reference count of @context. - * - * Returns: the same @context - * Since: 2.36 - */ - - -/** - * g_markup_parse_context_unref: - * @context: a #GMarkupParseContext - * - * Decreases the reference count of @context. When its reference count - * drops to 0, it is freed. - * - * Since: 2.36 - */ - - -/** - * g_markup_printf_escaped: - * @format: printf() style format string - * @...: the arguments to insert in the format string - * - * Formats arguments according to @format, escaping - * all string and character arguments in the fashion - * of g_markup_escape_text(). This is useful when you - * want to insert literal strings into XML-style markup - * output, without having to worry that the strings - * might themselves contain markup. - * - * |[<!-- language="C" --> - * const char *store = "Fortnum & Mason"; - * const char *item = "Tea"; - * char *output; - * - * output = g_markup_printf_escaped ("<purchase>" - * "<store>%s</store>" - * "<item>%s</item>" - * "</purchase>", - * store, item); - * ]| - * - * Returns: newly allocated result from formatting - * operation. Free with g_free(). - * Since: 2.4 - */ - - -/** - * g_markup_vprintf_escaped: - * @format: printf() style format string - * @args: variable argument list, similar to vprintf() - * - * Formats the data in @args according to @format, escaping - * all string and character arguments in the fashion - * of g_markup_escape_text(). See g_markup_printf_escaped(). - * - * Returns: newly allocated result from formatting - * operation. Free with g_free(). - * Since: 2.4 - */ - - -/** - * g_match_info_expand_references: - * @match_info: (nullable): a #GMatchInfo or %NULL - * @string_to_expand: the string to expand - * @error: location to store the error occurring, or %NULL to ignore errors - * - * Returns a new string containing the text in @string_to_expand with - * references and escape sequences expanded. References refer to the last - * match done with @string against @regex and have the same syntax used by - * g_regex_replace(). - * - * The @string_to_expand must be UTF-8 encoded even if #G_REGEX_RAW was - * passed to g_regex_new(). - * - * The backreferences are extracted from the string passed to the match - * function, so you cannot call this function after freeing the string. - * - * @match_info may be %NULL in which case @string_to_expand must not - * contain references. For instance "foo\n" does not refer to an actual - * pattern and '\n' merely will be replaced with \n character, - * while to expand "\0" (whole match) one needs the result of a match. - * Use g_regex_check_replacement() to find out whether @string_to_expand - * contains references. - * - * Returns: (nullable): the expanded string, or %NULL if an error occurred - * Since: 2.14 - */ - - -/** - * g_match_info_fetch: - * @match_info: #GMatchInfo structure - * @match_num: number of the sub expression - * - * Retrieves the text matching the @match_num'th capturing - * parentheses. 0 is the full text of the match, 1 is the first paren - * set, 2 the second, and so on. - * - * If @match_num is a valid sub pattern but it didn't match anything - * (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty - * string is returned. - * - * If the match was obtained using the DFA algorithm, that is using - * g_regex_match_all() or g_regex_match_all_full(), the retrieved - * string is not that of a set of parentheses but that of a matched - * substring. Substrings are matched in reverse order of length, so - * 0 is the longest match. - * - * The string is fetched from the string passed to the match function, - * so you cannot call this function after freeing the string. - * - * Returns: (nullable): The matched substring, or %NULL if an error - * occurred. You have to free the string yourself - * Since: 2.14 - */ - - -/** - * g_match_info_fetch_all: - * @match_info: a #GMatchInfo structure - * - * Bundles up pointers to each of the matching substrings from a match - * and stores them in an array of gchar pointers. The first element in - * the returned array is the match number 0, i.e. the entire matched - * text. - * - * If a sub pattern didn't match anything (e.g. sub pattern 1, matching - * "b" against "(a)?b") then an empty string is inserted. - * - * If the last match was obtained using the DFA algorithm, that is using - * g_regex_match_all() or g_regex_match_all_full(), the retrieved - * strings are not that matched by sets of parentheses but that of the - * matched substring. Substrings are matched in reverse order of length, - * so the first one is the longest match. - * - * The strings are fetched from the string passed to the match function, - * so you cannot call this function after freeing the string. - * - * Returns: (transfer full): a %NULL-terminated array of gchar * - * pointers. It must be freed using g_strfreev(). If the previous - * match failed %NULL is returned - * Since: 2.14 - */ - - -/** - * g_match_info_fetch_named: - * @match_info: #GMatchInfo structure - * @name: name of the subexpression - * - * Retrieves the text matching the capturing parentheses named @name. - * - * If @name is a valid sub pattern name but it didn't match anything - * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") - * then an empty string is returned. - * - * The string is fetched from the string passed to the match function, - * so you cannot call this function after freeing the string. - * - * Returns: (nullable): The matched substring, or %NULL if an error - * occurred. You have to free the string yourself - * Since: 2.14 - */ - - -/** - * g_match_info_fetch_named_pos: - * @match_info: #GMatchInfo structure - * @name: name of the subexpression - * @start_pos: (out) (optional): pointer to location where to store - * the start position, or %NULL - * @end_pos: (out) (optional): pointer to location where to store - * the end position, or %NULL - * - * Retrieves the position in bytes of the capturing parentheses named @name. - * - * If @name is a valid sub pattern name but it didn't match anything - * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") - * then @start_pos and @end_pos are set to -1 and %TRUE is returned. - * - * Returns: %TRUE if the position was fetched, %FALSE otherwise. - * If the position cannot be fetched, @start_pos and @end_pos - * are left unchanged. - * Since: 2.14 - */ - - -/** - * g_match_info_fetch_pos: - * @match_info: #GMatchInfo structure - * @match_num: number of the sub expression - * @start_pos: (out) (optional): pointer to location where to store - * the start position, or %NULL - * @end_pos: (out) (optional): pointer to location where to store - * the end position, or %NULL - * - * Retrieves the position in bytes of the @match_num'th capturing - * parentheses. 0 is the full text of the match, 1 is the first - * paren set, 2 the second, and so on. - * - * If @match_num is a valid sub pattern but it didn't match anything - * (e.g. sub pattern 1, matching "b" against "(a)?b") then @start_pos - * and @end_pos are set to -1 and %TRUE is returned. - * - * If the match was obtained using the DFA algorithm, that is using - * g_regex_match_all() or g_regex_match_all_full(), the retrieved - * position is not that of a set of parentheses but that of a matched - * substring. Substrings are matched in reverse order of length, so - * 0 is the longest match. - * - * Returns: %TRUE if the position was fetched, %FALSE otherwise. If - * the position cannot be fetched, @start_pos and @end_pos are left - * unchanged - * Since: 2.14 - */ - - -/** - * g_match_info_free: - * @match_info: (nullable): a #GMatchInfo, or %NULL - * - * If @match_info is not %NULL, calls g_match_info_unref(); otherwise does - * nothing. - * - * Since: 2.14 - */ - - -/** - * g_match_info_get_match_count: - * @match_info: a #GMatchInfo structure - * - * Retrieves the number of matched substrings (including substring 0, - * that is the whole matched text), so 1 is returned if the pattern - * has no substrings in it and 0 is returned if the match failed. - * - * If the last match was obtained using the DFA algorithm, that is - * using g_regex_match_all() or g_regex_match_all_full(), the retrieved - * count is not that of the number of capturing parentheses but that of - * the number of matched substrings. - * - * Returns: Number of matched substrings, or -1 if an error occurred - * Since: 2.14 - */ - - -/** - * g_match_info_get_regex: - * @match_info: a #GMatchInfo - * - * Returns #GRegex object used in @match_info. It belongs to Glib - * and must not be freed. Use g_regex_ref() if you need to keep it - * after you free @match_info object. - * - * Returns: #GRegex object used in @match_info - * Since: 2.14 - */ - - -/** - * g_match_info_get_string: - * @match_info: a #GMatchInfo - * - * Returns the string searched with @match_info. This is the - * string passed to g_regex_match() or g_regex_replace() so - * you may not free it before calling this function. - * - * Returns: the string searched with @match_info - * Since: 2.14 - */ - - -/** - * g_match_info_is_partial_match: - * @match_info: a #GMatchInfo structure - * - * Usually if the string passed to g_regex_match*() matches as far as - * it goes, but is too short to match the entire pattern, %FALSE is - * returned. There are circumstances where it might be helpful to - * distinguish this case from other cases in which there is no match. - * - * Consider, for example, an application where a human is required to - * type in data for a field with specific formatting requirements. An - * example might be a date in the form ddmmmyy, defined by the pattern - * "^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$". - * If the application sees the user’s keystrokes one by one, and can - * check that what has been typed so far is potentially valid, it is - * able to raise an error as soon as a mistake is made. - * - * GRegex supports the concept of partial matching by means of the - * #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD flags. - * When they are used, the return code for - * g_regex_match() or g_regex_match_full() is, as usual, %TRUE - * for a complete match, %FALSE otherwise. But, when these functions - * return %FALSE, you can check if the match was partial calling - * g_match_info_is_partial_match(). - * - * The difference between #G_REGEX_MATCH_PARTIAL_SOFT and - * #G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered - * with #G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a - * possible complete match, while with #G_REGEX_MATCH_PARTIAL_HARD matching - * stops at the partial match. - * When both #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD - * are set, the latter takes precedence. - * - * There were formerly some restrictions on the pattern for partial matching. - * The restrictions no longer apply. - * - * See pcrepartial(3) for more information on partial matching. - * - * Returns: %TRUE if the match was partial, %FALSE otherwise - * Since: 2.14 - */ - - -/** - * g_match_info_matches: - * @match_info: a #GMatchInfo structure - * - * Returns whether the previous match operation succeeded. - * - * Returns: %TRUE if the previous match operation succeeded, - * %FALSE otherwise - * Since: 2.14 - */ - - -/** - * g_match_info_next: - * @match_info: a #GMatchInfo structure - * @error: location to store the error occurring, or %NULL to ignore errors - * - * Scans for the next match using the same parameters of the previous - * call to g_regex_match_full() or g_regex_match() that returned - * @match_info. - * - * The match is done on the string passed to the match function, so you - * cannot free it before calling this function. - * - * Returns: %TRUE is the string matched, %FALSE otherwise - * Since: 2.14 - */ - - -/** - * g_match_info_ref: - * @match_info: a #GMatchInfo - * - * Increases reference count of @match_info by 1. - * - * Returns: @match_info - * Since: 2.30 - */ - - -/** - * g_match_info_unref: - * @match_info: a #GMatchInfo - * - * Decreases reference count of @match_info by 1. When reference count drops - * to zero, it frees all the memory associated with the match_info structure. - * - * Since: 2.30 - */ - - -/** - * g_mem_gc_friendly: - * - * This variable is %TRUE if the `G_DEBUG` environment variable - * includes the key `gc-friendly`. - */ - - -/** - * g_mem_is_system_malloc: - * - * Checks whether the allocator used by g_malloc() is the system's - * malloc implementation. If it returns %TRUE memory allocated with - * malloc() can be used interchangeably with memory allocated using g_malloc(). - * This function is useful for avoiding an extra copy of allocated memory returned - * by a non-GLib-based API. - * - * Returns: if %TRUE, malloc() and g_malloc() can be mixed. - * Deprecated: 2.46: GLib always uses the system malloc, so this function always - * returns %TRUE. - */ - - -/** - * g_mem_profile: - * - * GLib used to support some tools for memory profiling, but this - * no longer works. There are many other useful tools for memory - * profiling these days which can be used instead. - * - * Deprecated: 2.46: Use other memory profiling tools instead - */ - - -/** - * g_mem_set_vtable: - * @vtable: table of memory allocation routines. - * - * This function used to let you override the memory allocation function. - * However, its use was incompatible with the use of global constructors - * in GLib and GIO, because those use the GLib allocators before main is - * reached. Therefore this function is now deprecated and is just a stub. - * - * Deprecated: 2.46: This function now does nothing. Use other memory - * profiling tools instead - */ - - -/** - * g_memdup: - * @mem: the memory to copy. - * @byte_size: the number of bytes to copy. - * - * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it - * from @mem. If @mem is %NULL it returns %NULL. - * - * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem - * is %NULL. - * Deprecated: 2.68: Use g_memdup2() instead, as it accepts a #gsize argument - * for @byte_size, avoiding the possibility of overflow in a #gsize → #guint - * conversion - */ - - -/** - * g_memdup2: - * @mem: (nullable): the memory to copy. - * @byte_size: the number of bytes to copy. - * - * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it - * from @mem. If @mem is %NULL it returns %NULL. - * - * This replaces g_memdup(), which was prone to integer overflows when - * converting the argument from a #gsize to a #guint. - * - * Returns: (nullable): a pointer to the newly-allocated copy of the memory, - * or %NULL if @mem is %NULL. - * Since: 2.68 - */ - - -/** - * g_memmove: - * @dest: the destination address to copy the bytes to. - * @src: the source address to copy the bytes from. - * @len: the number of bytes to copy. - * - * Copies a block of memory @len bytes long, from @src to @dest. - * The source and destination areas may overlap. - * - * Deprecated: 2.40: Just use memmove(). - */ - - -/** - * g_message: - * @...: format string, followed by parameters to insert - * into the format string (as with printf()) - * - * A convenience function/macro to log a normal message. - * - * 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_mkdir: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * @mode: permissions to use for the newly created directory - * - * A wrapper for the POSIX mkdir() function. The mkdir() function - * attempts to create a directory with the given name and permissions. - * The mode argument is ignored on Windows. - * - * See your C library manual for more details about mkdir(). - * - * Returns: 0 if the directory was successfully created, -1 if an error - * occurred - * Since: 2.6 - */ - - -/** - * g_mkdir_with_parents: - * @pathname: (type filename): a pathname in the GLib file name encoding - * @mode: permissions to use for newly created directories - * - * Create a directory if it doesn't already exist. Create intermediate - * parent directories as needed, too. - * - * Returns: 0 if the directory already exists, or was successfully - * created. Returns -1 if an error occurred, with errno set. - * Since: 2.8 - */ - - -/** - * g_mkdtemp: (skip) - * @tmpl: (type filename): template directory name - * - * Creates a temporary directory. See the mkdtemp() documentation - * on most UNIX-like systems. - * - * The parameter is a string that should follow the rules for - * mkdtemp() templates, i.e. contain the string "XXXXXX". - * g_mkdtemp() is slightly more flexible than mkdtemp() in that the - * sequence does not have to occur at the very end of the template. - * The X string will be modified to form the name of a directory that - * didn't exist. - * The string should be in the GLib file name encoding. Most importantly, - * on Windows it should be in UTF-8. - * - * If you are going to be creating a temporary directory inside the - * directory returned by g_get_tmp_dir(), you might want to use - * g_dir_make_tmp() instead. - * - * Returns: (nullable) (type filename): A pointer to @tmpl, which has been - * modified to hold the directory name. In case of errors, %NULL is - * returned and %errno will be set. - * Since: 2.30 - */ - - -/** - * g_mkdtemp_full: (skip) - * @tmpl: (type filename): template directory name - * @mode: permissions to create the temporary directory with - * - * Creates a temporary directory. See the mkdtemp() documentation - * on most UNIX-like systems. - * - * The parameter is a string that should follow the rules for - * mkdtemp() templates, i.e. contain the string "XXXXXX". - * g_mkdtemp_full() is slightly more flexible than mkdtemp() in that the - * sequence does not have to occur at the very end of the template - * and you can pass a @mode. The X string will be modified to form - * the name of a directory that didn't exist. The string should be - * in the GLib file name encoding. Most importantly, on Windows it - * should be in UTF-8. - * - * If you are going to be creating a temporary directory inside the - * directory returned by g_get_tmp_dir(), you might want to use - * g_dir_make_tmp() instead. - * - * Returns: (nullable) (type filename): A pointer to @tmpl, which has been - * modified to hold the directory name. In case of errors, %NULL is - * returned, and %errno will be set. - * Since: 2.30 - */ - - -/** - * g_mkstemp: (skip) - * @tmpl: (type filename): template filename - * - * Opens a temporary file. See the mkstemp() documentation - * on most UNIX-like systems. - * - * The parameter is a string that should follow the rules for - * mkstemp() templates, i.e. contain the string "XXXXXX". - * g_mkstemp() is slightly more flexible than mkstemp() in that the - * sequence does not have to occur at the very end of the template. - * The X string will be modified to form the name of a file that - * didn't exist. The string should be in the GLib file name encoding. - * Most importantly, on Windows it should be in UTF-8. - * - * Returns: A file handle (as from open()) to the file - * opened for reading and writing. The file is opened in binary - * mode on platforms where there is a difference. The file handle - * should be closed with close(). In case of errors, -1 is - * returned and %errno will be set. - */ - - -/** - * g_mkstemp_full: (skip) - * @tmpl: (type filename): template filename - * @flags: flags to pass to an open() call in addition to O_EXCL - * and O_CREAT, which are passed automatically - * @mode: permissions to create the temporary file with - * - * Opens a temporary file. See the mkstemp() documentation - * on most UNIX-like systems. - * - * The parameter is a string that should follow the rules for - * mkstemp() templates, i.e. contain the string "XXXXXX". - * g_mkstemp_full() is slightly more flexible than mkstemp() - * in that the sequence does not have to occur at the very end of the - * template and you can pass a @mode and additional @flags. The X - * string will be modified to form the name of a file that didn't exist. - * The string should be in the GLib file name encoding. Most importantly, - * on Windows it should be in UTF-8. - * - * Returns: A file handle (as from open()) to the file - * opened for reading and writing. The file handle should be - * closed with close(). In case of errors, -1 is returned - * and %errno will be set. - * Since: 2.22 - */ - - -/** - * g_mutex_clear: - * @mutex: an initialized #GMutex - * - * Frees the resources allocated to a mutex with g_mutex_init(). - * - * This function should not be used with a #GMutex that has been - * statically allocated. - * - * Calling g_mutex_clear() on a locked mutex leads to undefined - * behaviour. - * - * Sine: 2.32 - */ - - -/** - * g_mutex_init: - * @mutex: an uninitialized #GMutex - * - * Initializes a #GMutex so that it can be used. - * - * This function is useful to initialize a mutex that has been - * allocated on the stack, or as part of a larger structure. - * It is not necessary to initialize a mutex that has been - * statically allocated. - * - * |[<!-- language="C" --> - * typedef struct { - * GMutex m; - * ... - * } Blob; - * - * Blob *b; - * - * b = g_new (Blob, 1); - * g_mutex_init (&b->m); - * ]| - * - * To undo the effect of g_mutex_init() when a mutex is no longer - * needed, use g_mutex_clear(). - * - * Calling g_mutex_init() on an already initialized #GMutex leads - * to undefined behaviour. - * - * Since: 2.32 - */ - - -/** - * g_mutex_lock: - * @mutex: a #GMutex - * - * Locks @mutex. If @mutex is already locked by another thread, the - * current thread will block until @mutex is unlocked by the other - * thread. - * - * #GMutex is neither guaranteed to be recursive nor to be - * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has - * already been locked by the same thread results in undefined behaviour - * (including but not limited to deadlocks). - */ - - -/** - * g_mutex_trylock: - * @mutex: a #GMutex - * - * Tries to lock @mutex. If @mutex is already locked by another thread, - * it immediately returns %FALSE. Otherwise it locks @mutex and returns - * %TRUE. - * - * #GMutex is neither guaranteed to be recursive nor to be - * non-recursive. As such, calling g_mutex_lock() on a #GMutex that has - * already been locked by the same thread results in undefined behaviour - * (including but not limited to deadlocks or arbitrary return values). - * - * Returns: %TRUE if @mutex could be locked - */ - - -/** - * g_mutex_unlock: - * @mutex: a #GMutex - * - * Unlocks @mutex. If another thread is blocked in a g_mutex_lock() - * call for @mutex, it will become unblocked and can lock @mutex itself. - * - * Calling g_mutex_unlock() on a mutex that is not locked by the - * current thread leads to undefined behaviour. - */ - - -/** - * g_node_child_index: - * @node: a #GNode - * @data: the data to find - * - * Gets the position of the first child of a #GNode - * which contains the given data. - * - * Returns: the index of the child of @node which contains - * @data, or -1 if the data is not found - */ - - -/** - * g_node_child_position: - * @node: a #GNode - * @child: a child of @node - * - * Gets the position of a #GNode with respect to its siblings. - * @child must be a child of @node. The first child is numbered 0, - * the second 1, and so on. - * - * Returns: the position of @child with respect to its siblings - */ - - -/** - * g_node_children_foreach: - * @node: a #GNode - * @flags: which types of children are to be visited, one of - * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - * @func: the function to call for each visited node - * @data: user data to pass to the function - * - * Calls a function for each of the children of a #GNode. Note that it - * doesn't descend beneath the child nodes. @func must not do anything - * that would modify the structure of the tree. - */ - - -/** - * g_node_copy: - * @node: a #GNode - * - * Recursively copies a #GNode (but does not deep-copy the data inside the - * nodes, see g_node_copy_deep() if you need that). - * - * Returns: a new #GNode containing the same data pointers - */ - - -/** - * g_node_copy_deep: - * @node: a #GNode - * @copy_func: the function which is called to copy the data inside each node, - * or %NULL to use the original data. - * @data: data to pass to @copy_func - * - * Recursively copies a #GNode and its data. - * - * Returns: a new #GNode containing copies of the data in @node. - * Since: 2.4 - */ - - -/** - * g_node_depth: - * @node: a #GNode - * - * Gets the depth of a #GNode. - * - * If @node is %NULL the depth is 0. The root node has a depth of 1. - * For the children of the root node the depth is 2. And so on. - * - * Returns: the depth of the #GNode - */ - - -/** - * g_node_destroy: - * @root: the root of the tree/subtree to destroy - * - * Removes @root and its children from the tree, freeing any memory - * allocated. - */ - - -/** - * g_node_find: - * @root: the root #GNode of the tree to search - * @order: the order in which nodes are visited - %G_IN_ORDER, - * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER - * @flags: which types of children are to be searched, one of - * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - * @data: the data to find - * - * Finds a #GNode in a tree. - * - * Returns: the found #GNode, or %NULL if the data is not found - */ - - -/** - * g_node_find_child: - * @node: a #GNode - * @flags: which types of children are to be searched, one of - * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - * @data: the data to find - * - * Finds the first child of a #GNode with the given data. - * - * Returns: the found child #GNode, or %NULL if the data is not found - */ - - -/** - * g_node_first_sibling: - * @node: a #GNode - * - * Gets the first sibling of a #GNode. - * This could possibly be the node itself. - * - * Returns: the first sibling of @node - */ - - -/** - * g_node_get_root: - * @node: a #GNode - * - * Gets the root of a tree. - * - * Returns: the root of the tree - */ - - -/** - * g_node_insert: - * @parent: the #GNode to place @node under - * @position: the position to place @node at, with respect to its siblings - * If position is -1, @node is inserted as the last child of @parent - * @node: the #GNode to insert - * - * Inserts a #GNode beneath the parent at the given position. - * - * Returns: the inserted #GNode - */ - - -/** - * g_node_insert_after: - * @parent: the #GNode to place @node under - * @sibling: the sibling #GNode to place @node after. - * If sibling is %NULL, the node is inserted as the first child of @parent. - * @node: the #GNode to insert - * - * Inserts a #GNode beneath the parent after the given sibling. - * - * Returns: the inserted #GNode - */ - - -/** - * g_node_insert_before: - * @parent: the #GNode to place @node under - * @sibling: the sibling #GNode to place @node before. - * If sibling is %NULL, the node is inserted as the last child of @parent. - * @node: the #GNode to insert - * - * Inserts a #GNode beneath the parent before the given sibling. - * - * Returns: the inserted #GNode - */ - - -/** - * g_node_is_ancestor: - * @node: a #GNode - * @descendant: a #GNode - * - * Returns %TRUE if @node is an ancestor of @descendant. - * This is true if node is the parent of @descendant, - * or if node is the grandparent of @descendant etc. - * - * Returns: %TRUE if @node is an ancestor of @descendant - */ - - -/** - * g_node_last_child: - * @node: a #GNode (must not be %NULL) - * - * Gets the last child of a #GNode. - * - * Returns: the last child of @node, or %NULL if @node has no children - */ - - -/** - * g_node_last_sibling: - * @node: a #GNode - * - * Gets the last sibling of a #GNode. - * This could possibly be the node itself. - * - * Returns: the last sibling of @node - */ - - -/** - * g_node_max_height: - * @root: a #GNode - * - * Gets the maximum height of all branches beneath a #GNode. - * This is the maximum distance from the #GNode to all leaf nodes. - * - * If @root is %NULL, 0 is returned. If @root has no children, - * 1 is returned. If @root has children, 2 is returned. And so on. - * - * Returns: the maximum height of the tree beneath @root - */ - - -/** - * g_node_n_children: - * @node: a #GNode - * - * Gets the number of children of a #GNode. - * - * Returns: the number of children of @node - */ - - -/** - * g_node_n_nodes: - * @root: a #GNode - * @flags: which types of children are to be counted, one of - * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - * - * Gets the number of nodes in a tree. - * - * Returns: the number of nodes in the tree - */ - - -/** - * g_node_new: - * @data: the data of the new node - * - * Creates a new #GNode containing the given data. - * Used to create the first node in a tree. - * - * Returns: a new #GNode - */ - - -/** - * g_node_nth_child: - * @node: a #GNode - * @n: the index of the desired child - * - * Gets a child of a #GNode, using the given index. - * The first child is at index 0. If the index is - * too big, %NULL is returned. - * - * Returns: the child of @node at index @n - */ - - -/** - * g_node_prepend: - * @parent: the #GNode to place the new #GNode under - * @node: the #GNode to insert - * - * Inserts a #GNode as the first child of the given parent. - * - * Returns: the inserted #GNode - */ - - -/** - * g_node_reverse_children: - * @node: a #GNode. - * - * Reverses the order of the children of a #GNode. - * (It doesn't change the order of the grandchildren.) - */ - - -/** - * g_node_traverse: - * @root: the root #GNode of the tree to traverse - * @order: the order in which nodes are visited - %G_IN_ORDER, - * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER. - * @flags: which types of children are to be visited, one of - * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - * @max_depth: the maximum depth of the traversal. Nodes below this - * depth will not be visited. If max_depth is -1 all nodes in - * the tree are visited. If depth is 1, only the root is visited. - * If depth is 2, the root and its children are visited. And so on. - * @func: the function to call for each visited #GNode - * @data: user data to pass to the function - * - * Traverses a tree starting at the given root #GNode. - * It calls the given function for each node visited. - * The traversal can be halted at any point by returning %TRUE from @func. - * @func must not do anything that would modify the structure of the tree. - */ - - -/** - * g_node_unlink: - * @node: the #GNode to unlink, which becomes the root of a new tree - * - * Unlinks a #GNode from a tree, resulting in two separate trees. - */ - - -/** - * g_ntohl: - * @val: a 32-bit integer value in network byte order - * - * Converts a 32-bit integer value from network to host byte order. - * - * Returns: @val converted to host byte order. - */ - - -/** - * g_ntohs: - * @val: a 16-bit integer value in network byte order - * - * Converts a 16-bit integer value from network to host byte order. - * - * Returns: @val converted to host byte order - */ - - -/** - * g_nullify_pointer: - * @nullify_location: (not nullable): the memory address of the pointer. - * - * Set the pointer at the specified location to %NULL. - */ - - -/** - * g_on_error_query: - * @prg_name: the program name, needed by gdb for the "[S]tack trace" - * option. If @prg_name is %NULL, g_get_prgname() is called to get - * the program name (which will work correctly if gdk_init() or - * gtk_init() has been called) - * - * Prompts the user with - * `[E]xit, [H]alt, show [S]tack trace or [P]roceed`. - * This function is intended to be used for debugging use only. - * The following example shows how it can be used together with - * the g_log() functions. - * - * |[<!-- language="C" --> - * #include <glib.h> - * - * static void - * log_handler (const gchar *log_domain, - * GLogLevelFlags log_level, - * const gchar *message, - * gpointer user_data) - * { - * g_log_default_handler (log_domain, log_level, message, user_data); - * - * g_on_error_query (MY_PROGRAM_NAME); - * } - * - * int - * main (int argc, char *argv[]) - * { - * g_log_set_handler (MY_LOG_DOMAIN, - * G_LOG_LEVEL_WARNING | - * G_LOG_LEVEL_ERROR | - * G_LOG_LEVEL_CRITICAL, - * log_handler, - * NULL); - * ... - * ]| - * - * If "[E]xit" is selected, the application terminates with a call - * to _exit(0). - * - * If "[S]tack" trace is selected, g_on_error_stack_trace() is called. - * This invokes gdb, which attaches to the current process and shows - * a stack trace. The prompt is then shown again. - * - * If "[P]roceed" is selected, the function returns. - * - * This function may cause different actions on non-UNIX platforms. - * - * On Windows consider using the `G_DEBUGGER` environment - * variable (see [Running GLib Applications](glib-running.html)) and - * calling g_on_error_stack_trace() instead. - */ - - -/** - * g_on_error_stack_trace: - * @prg_name: the program name, needed by gdb for the "[S]tack trace" - * option - * - * Invokes gdb, which attaches to the current process and shows a - * stack trace. Called by g_on_error_query() when the "[S]tack trace" - * option is selected. You can get the current process's program name - * with g_get_prgname(), assuming that you have called gtk_init() or - * gdk_init(). - * - * This function may cause different actions on non-UNIX platforms. - * - * When running on Windows, this function is *not* called by - * g_on_error_query(). If called directly, it will raise an - * exception, which will crash the program. If the `G_DEBUGGER` environment - * variable is set, a debugger will be invoked to attach and - * handle that exception (see [Running GLib Applications](glib-running.html)). - */ - - -/** - * g_once: - * @once: a #GOnce structure - * @func: the #GThreadFunc function associated to @once. This function - * is called only once, regardless of the number of times it and - * its associated #GOnce struct are passed to g_once(). - * @arg: data to be passed to @func - * - * The first call to this routine by a process with a given #GOnce - * struct calls @func with the given argument. Thereafter, subsequent - * calls to g_once() with the same #GOnce struct do not call @func - * again, but return the stored result of the first call. On return - * from g_once(), the status of @once will be %G_ONCE_STATUS_READY. - * - * For example, a mutex or a thread-specific data key must be created - * exactly once. In a threaded environment, calling g_once() ensures - * that the initialization is serialized across multiple threads. - * - * Calling g_once() recursively on the same #GOnce struct in - * @func will lead to a deadlock. - * - * |[<!-- language="C" --> - * gpointer - * get_debug_flags (void) - * { - * static GOnce my_once = G_ONCE_INIT; - * - * g_once (&my_once, parse_debug_flags, NULL); - * - * return my_once.retval; - * } - * ]| - * - * Since: 2.4 - */ - - -/** - * g_once_init_enter: - * @location: (not nullable): location of a static initializable variable - * containing 0 - * - * Function to be called when starting a critical initialization - * section. The argument @location must point to a static - * 0-initialized variable that will be set to a value other than 0 at - * the end of the initialization section. In combination with - * g_once_init_leave() and the unique address @value_location, it can - * be ensured that an initialization section will be executed only once - * during a program's life time, and that concurrent threads are - * blocked until initialization completed. To be used in constructs - * like this: - * - * |[<!-- language="C" --> - * static gsize initialization_value = 0; - * - * if (g_once_init_enter (&initialization_value)) - * { - * gsize setup_value = 42; // initialization code here - * - * g_once_init_leave (&initialization_value, setup_value); - * } - * - * // use initialization_value here - * ]| - * - * While @location has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Returns: %TRUE if the initialization section should be entered, - * %FALSE and blocks otherwise - * Since: 2.14 - */ - - -/** - * g_once_init_leave: - * @location: (not nullable): location of a static initializable variable - * containing 0 - * @result: new non-0 value for *@value_location - * - * Counterpart to g_once_init_enter(). Expects a location of a static - * 0-initialized initialization variable, and an initialization value - * other than 0. Sets the variable to the initialization value, and - * releases concurrent threads blocking in g_once_init_enter() on this - * initialization variable. - * - * While @location has a `volatile` qualifier, this is a historical artifact and - * the pointer passed to it should not be `volatile`. - * - * Since: 2.14 - */ - - -/** - * g_open: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * @flags: as in open() - * @mode: as in open() - * - * A wrapper for the POSIX open() function. The open() function is - * used to convert a pathname into a file descriptor. - * - * On POSIX systems file descriptors are implemented by the operating - * system. On Windows, it's the C library that implements open() and - * file descriptors. The actual Win32 API for opening files is quite - * 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 open(). - * - * Returns: a new file descriptor, or -1 if an error occurred. - * The return value can be used exactly like the return value - * from open(). - * Since: 2.6 - */ - - -/** - * g_option_context_add_group: - * @context: a #GOptionContext - * @group: (transfer full): the group to add - * - * Adds a #GOptionGroup to the @context, so that parsing with @context - * will recognize the options in the group. Note that this will take - * ownership of the @group and thus the @group should not be freed. - * - * Since: 2.6 - */ - - -/** - * g_option_context_add_main_entries: - * @context: a #GOptionContext - * @entries: (array zero-terminated=1): a %NULL-terminated array of #GOptionEntrys - * @translation_domain: (nullable): a translation domain to use for translating - * the `--help` output for the options in @entries - * with gettext(), or %NULL - * - * A convenience function which creates a main group if it doesn't - * exist, adds the @entries to it and sets the translation domain. - * - * Since: 2.6 - */ - - -/** - * g_option_context_free: - * @context: a #GOptionContext - * - * Frees context and all the groups which have been - * added to it. - * - * Please note that parsed arguments need to be freed separately (see - * #GOptionEntry). - * - * Since: 2.6 - */ - - -/** - * g_option_context_get_description: - * @context: a #GOptionContext - * - * Returns the description. See g_option_context_set_description(). - * - * Returns: the description - * Since: 2.12 - */ - - -/** - * g_option_context_get_help: - * @context: a #GOptionContext - * @main_help: if %TRUE, only include the main group - * @group: (nullable): the #GOptionGroup to create help for, or %NULL - * - * Returns a formatted, translated help text for the given context. - * To obtain the text produced by `--help`, call - * `g_option_context_get_help (context, TRUE, NULL)`. - * To obtain the text produced by `--help-all`, call - * `g_option_context_get_help (context, FALSE, NULL)`. - * To obtain the help text for an option group, call - * `g_option_context_get_help (context, FALSE, group)`. - * - * Returns: A newly allocated string containing the help text - * Since: 2.14 - */ - - -/** - * g_option_context_get_help_enabled: - * @context: a #GOptionContext - * - * Returns whether automatic `--help` generation - * is turned on for @context. See g_option_context_set_help_enabled(). - * - * Returns: %TRUE if automatic help generation is turned on. - * Since: 2.6 - */ - - -/** - * g_option_context_get_ignore_unknown_options: - * @context: a #GOptionContext - * - * Returns whether unknown options are ignored or not. See - * g_option_context_set_ignore_unknown_options(). - * - * Returns: %TRUE if unknown options are ignored. - * Since: 2.6 - */ - - -/** - * g_option_context_get_main_group: - * @context: a #GOptionContext - * - * Returns a pointer to the main group of @context. - * - * Returns: (transfer none): the main group of @context, or %NULL if - * @context doesn't have a main group. Note that group belongs to - * @context and should not be modified or freed. - * Since: 2.6 - */ - - -/** - * g_option_context_get_strict_posix: - * @context: a #GOptionContext - * - * Returns whether strict POSIX code is enabled. - * - * See g_option_context_set_strict_posix() for more information. - * - * Returns: %TRUE if strict POSIX is enabled, %FALSE otherwise. - * Since: 2.44 - */ - - -/** - * g_option_context_get_summary: - * @context: a #GOptionContext - * - * Returns the summary. See g_option_context_set_summary(). - * - * Returns: the summary - * Since: 2.12 - */ - - -/** - * g_option_context_new: - * @parameter_string: (nullable): a string which is displayed in - * the first line of `--help` output, after the usage summary - * `programname [OPTION...]` - * - * Creates a new option context. - * - * The @parameter_string can serve multiple purposes. It can be used - * to add descriptions for "rest" arguments, which are not parsed by - * the #GOptionContext, typically something like "FILES" or - * "FILE1 FILE2...". If you are using #G_OPTION_REMAINING for - * collecting "rest" arguments, GLib handles this automatically by - * using the @arg_description of the corresponding #GOptionEntry in - * the usage summary. - * - * Another usage is to give a short summary of the program - * functionality, like " - frob the strings", which will be displayed - * in the same line as the usage. For a longer description of the - * program functionality that should be displayed as a paragraph - * below the usage line, use g_option_context_set_summary(). - * - * Note that the @parameter_string is translated using the - * function set with g_option_context_set_translate_func(), so - * it should normally be passed untranslated. - * - * Returns: a newly created #GOptionContext, which must be - * freed with g_option_context_free() after use. - * Since: 2.6 - */ - - -/** - * g_option_context_parse: - * @context: a #GOptionContext - * @argc: (inout) (optional): a pointer to the number of command line arguments - * @argv: (inout) (array length=argc) (optional): a pointer to the array of command line arguments - * @error: a return location for errors - * - * Parses the command line arguments, recognizing options - * which have been added to @context. A side-effect of - * calling this function is that g_set_prgname() will be - * called. - * - * If the parsing is successful, any parsed arguments are - * removed from the array and @argc and @argv are updated - * accordingly. A '--' option is stripped from @argv - * unless there are unparsed options before and after it, - * or some of the options after it start with '-'. In case - * of an error, @argc and @argv are left unmodified. - * - * If automatic `--help` support is enabled - * (see g_option_context_set_help_enabled()), and the - * @argv array contains one of the recognized help options, - * this function will produce help output to stdout and - * call `exit (0)`. - * - * Note that function depends on the [current locale][setlocale] for - * automatic character set conversion of string and filename - * arguments. - * - * Returns: %TRUE if the parsing was successful, - * %FALSE if an error occurred - * Since: 2.6 - */ - - -/** - * g_option_context_parse_strv: - * @context: a #GOptionContext - * @arguments: (inout) (array null-terminated=1) (optional): a pointer - * to the command line arguments (which must be in UTF-8 on Windows). - * Starting with GLib 2.62, @arguments can be %NULL, which matches - * g_option_context_parse(). - * @error: a return location for errors - * - * Parses the command line arguments. - * - * This function is similar to g_option_context_parse() except that it - * respects the normal memory rules when dealing with a strv instead of - * assuming that the passed-in array is the argv of the main function. - * - * In particular, strings that are removed from the arguments list will - * be freed using g_free(). - * - * On Windows, the strings are expected to be in UTF-8. This is in - * contrast to g_option_context_parse() which expects them to be in the - * system codepage, which is how they are passed as @argv to main(). - * See g_win32_get_command_line() for a solution. - * - * This function is useful if you are trying to use #GOptionContext with - * #GApplication. - * - * Returns: %TRUE if the parsing was successful, - * %FALSE if an error occurred - * Since: 2.40 - */ - - -/** - * g_option_context_set_description: - * @context: a #GOptionContext - * @description: (nullable): a string to be shown in `--help` output - * after the list of options, or %NULL - * - * Adds a string to be displayed in `--help` output after the list - * of options. This text often includes a bug reporting address. - * - * Note that the summary is translated (see - * g_option_context_set_translate_func()). - * - * Since: 2.12 - */ - - -/** - * g_option_context_set_help_enabled: - * @context: a #GOptionContext - * @help_enabled: %TRUE to enable `--help`, %FALSE to disable it - * - * Enables or disables automatic generation of `--help` output. - * By default, g_option_context_parse() recognizes `--help`, `-h`, - * `-?`, `--help-all` and `--help-groupname` and creates suitable - * output to stdout. - * - * Since: 2.6 - */ - - -/** - * g_option_context_set_ignore_unknown_options: - * @context: a #GOptionContext - * @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce - * an error when unknown options are met - * - * Sets whether to ignore unknown options or not. If an argument is - * ignored, it is left in the @argv array after parsing. By default, - * g_option_context_parse() treats unknown options as error. - * - * This setting does not affect non-option arguments (i.e. arguments - * which don't start with a dash). But note that GOption cannot reliably - * determine whether a non-option belongs to a preceding unknown option. - * - * Since: 2.6 - */ - - -/** - * g_option_context_set_main_group: - * @context: a #GOptionContext - * @group: (transfer full): the group to set as main group - * - * Sets a #GOptionGroup as main group of the @context. - * This has the same effect as calling g_option_context_add_group(), - * the only difference is that the options in the main group are - * treated differently when generating `--help` output. - * - * Since: 2.6 - */ - - -/** - * g_option_context_set_strict_posix: - * @context: a #GOptionContext - * @strict_posix: the new value - * - * Sets strict POSIX mode. - * - * By default, this mode is disabled. - * - * In strict POSIX mode, the first non-argument parameter encountered - * (eg: filename) terminates argument processing. Remaining arguments - * are treated as non-options and are not attempted to be parsed. - * - * If strict POSIX mode is disabled then parsing is done in the GNU way - * where option arguments can be freely mixed with non-options. - * - * As an example, consider "ls foo -l". With GNU style parsing, this - * will list "foo" in long mode. In strict POSIX style, this will list - * the files named "foo" and "-l". - * - * It may be useful to force strict POSIX mode when creating "verb - * style" command line tools. For example, the "gsettings" command line - * tool supports the global option "--schemadir" as well as many - * subcommands ("get", "set", etc.) which each have their own set of - * arguments. Using strict POSIX mode will allow parsing the global - * options up to the verb name while leaving the remaining options to be - * parsed by the relevant subcommand (which can be determined by - * examining the verb name, which should be present in argv[1] after - * parsing). - * - * Since: 2.44 - */ - - -/** - * g_option_context_set_summary: - * @context: a #GOptionContext - * @summary: (nullable): a string to be shown in `--help` output - * before the list of options, or %NULL - * - * Adds a string to be displayed in `--help` output before the list - * of options. This is typically a summary of the program functionality. - * - * Note that the summary is translated (see - * g_option_context_set_translate_func() and - * g_option_context_set_translation_domain()). - * - * Since: 2.12 - */ - - -/** - * g_option_context_set_translate_func: - * @context: a #GOptionContext - * @func: (nullable): the #GTranslateFunc, or %NULL - * @data: (nullable): user data to pass to @func, or %NULL - * @destroy_notify: (nullable): a function which gets called to free @data, or %NULL - * - * Sets the function which is used to translate the contexts - * user-visible strings, for `--help` output. If @func is %NULL, - * strings are not translated. - * - * Note that option groups have their own translation functions, - * this function only affects the @parameter_string (see g_option_context_new()), - * the summary (see g_option_context_set_summary()) and the description - * (see g_option_context_set_description()). - * - * If you are using gettext(), you only need to set the translation - * domain, see g_option_context_set_translation_domain(). - * - * Since: 2.12 - */ - - -/** - * g_option_context_set_translation_domain: - * @context: a #GOptionContext - * @domain: the domain to use - * - * A convenience function to use gettext() for translating - * user-visible strings. - * - * Since: 2.12 - */ - - -/** - * g_option_group_add_entries: - * @group: a #GOptionGroup - * @entries: (array zero-terminated=1): a %NULL-terminated array of #GOptionEntrys - * - * Adds the options specified in @entries to @group. - * - * Since: 2.6 - */ - - -/** - * g_option_group_free: - * @group: a #GOptionGroup - * - * Frees a #GOptionGroup. Note that you must not free groups - * which have been added to a #GOptionContext. - * - * Since: 2.6 - * Deprecated: 2.44: Use g_option_group_unref() instead. - */ - - -/** - * g_option_group_new: - * @name: the name for the option group, this is used to provide - * help for the options in this group with `--help-`@name - * @description: a description for this group to be shown in - * `--help`. This string is translated using the translation - * domain or translation function of the group - * @help_description: a description for the `--help-`@name option. - * This string is translated using the translation domain or translation function - * of the group - * @user_data: (nullable): user data that will be passed to the pre- and post-parse hooks, - * the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL - * @destroy: (nullable): a function that will be called to free @user_data, or %NULL - * - * Creates a new #GOptionGroup. - * - * Returns: a newly created option group. It should be added - * to a #GOptionContext or freed with g_option_group_unref(). - * Since: 2.6 - */ - - -/** - * g_option_group_ref: - * @group: a #GOptionGroup - * - * Increments the reference count of @group by one. - * - * Returns: a #GOptionGroup - * Since: 2.44 - */ - - -/** - * g_option_group_set_error_hook: - * @group: a #GOptionGroup - * @error_func: a function to call when an error occurs - * - * Associates a function with @group which will be called - * from g_option_context_parse() when an error occurs. - * - * Note that the user data to be passed to @error_func can be - * specified when constructing the group with g_option_group_new(). - * - * Since: 2.6 - */ - - -/** - * g_option_group_set_parse_hooks: - * @group: a #GOptionGroup - * @pre_parse_func: (nullable): a function to call before parsing, or %NULL - * @post_parse_func: (nullable): a function to call after parsing, or %NULL - * - * Associates two functions with @group which will be called - * from g_option_context_parse() before the first option is parsed - * and after the last option has been parsed, respectively. - * - * Note that the user data to be passed to @pre_parse_func and - * @post_parse_func can be specified when constructing the group - * with g_option_group_new(). - * - * Since: 2.6 - */ - - -/** - * g_option_group_set_translate_func: - * @group: a #GOptionGroup - * @func: (nullable): the #GTranslateFunc, or %NULL - * @data: (nullable): user data to pass to @func, or %NULL - * @destroy_notify: (nullable): a function which gets called to free @data, or %NULL - * - * Sets the function which is used to translate user-visible strings, - * for `--help` output. Different groups can use different - * #GTranslateFuncs. If @func is %NULL, strings are not translated. - * - * If you are using gettext(), you only need to set the translation - * domain, see g_option_group_set_translation_domain(). - * - * Since: 2.6 - */ - - -/** - * g_option_group_set_translation_domain: - * @group: a #GOptionGroup - * @domain: the domain to use - * - * A convenience function to use gettext() for translating - * user-visible strings. - * - * Since: 2.6 - */ - - -/** - * g_option_group_unref: - * @group: a #GOptionGroup - * - * Decrements the reference count of @group by one. - * If the reference count drops to 0, the @group will be freed. - * and all memory allocated by the @group is released. - * - * Since: 2.44 - */ - - -/** - * g_parse_debug_string: - * @string: (nullable): a list of debug options separated by colons, spaces, or - * commas, or %NULL. - * @keys: (array length=nkeys): pointer to an array of #GDebugKey which associate - * strings with bit flags. - * @nkeys: the number of #GDebugKeys in the array. - * - * Parses a string containing debugging options - * into a %guint containing bit flags. This is used - * within GDK and GTK+ to parse the debug options passed on the - * command line or through environment variables. - * - * If @string is equal to "all", all flags are set. Any flags - * specified along with "all" in @string are inverted; thus, - * "all,foo,bar" or "foo,bar,all" sets all flags except those - * corresponding to "foo" and "bar". - * - * If @string is equal to "help", all the available keys in @keys - * are printed out to standard error. - * - * Returns: the combined set of bit flags. - */ - - -/** - * g_path_get_basename: - * @file_name: (type filename): the name of the file - * - * Gets the last component of the filename. - * - * If @file_name ends with a directory separator it gets the component - * before the last slash. If @file_name consists only of directory - * separators (and on Windows, possibly a drive letter), a single - * separator is returned. If @file_name is empty, it gets ".". - * - * Returns: (type filename): a newly allocated string containing the last - * component of the filename - */ - - -/** - * g_path_get_dirname: - * @file_name: (type filename): the name of the file - * - * Gets the directory components of a file name. For example, the directory - * component of `/usr/bin/test` is `/usr/bin`. The directory component of `/` - * is `/`. - * - * If the file name has no directory components "." is returned. - * The returned string should be freed when no longer needed. - * - * Returns: (type filename): the directory components of the file - */ - - -/** - * g_path_is_absolute: - * @file_name: (type filename): a file name - * - * Returns %TRUE if the given @file_name is an absolute file name. - * Note that this is a somewhat vague concept on Windows. - * - * On POSIX systems, an absolute file name is well-defined. It always - * starts from the single root directory. For example "/usr/local". - * - * On Windows, the concepts of current drive and drive-specific - * current directory introduce vagueness. This function interprets as - * an absolute file name one that either begins with a directory - * separator such as "\Users\tml" or begins with the root on a drive, - * for example "C:\Windows". The first case also includes UNC paths - * such as "\\\\myserver\docs\foo". In all cases, either slashes or - * backslashes are accepted. - * - * Note that a file name relative to the current drive root does not - * truly specify a file uniquely over time and across processes, as - * the current drive is a per-process value and can be changed. - * - * File names relative the current directory on some specific drive, - * such as "D:foo/bar", are not interpreted as absolute by this - * function, but they obviously are not relative to the normal current - * directory as returned by getcwd() or g_get_current_dir() - * either. Such paths should be avoided, or need to be handled using - * Windows-specific code. - * - * Returns: %TRUE if @file_name is absolute - */ - - -/** - * g_path_skip_root: - * @file_name: (type filename): a file name - * - * Returns a pointer into @file_name after the root component, - * i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name - * is not an absolute path it returns %NULL. - * - * Returns: (type filename) (nullable): a pointer into @file_name after the - * root component - */ - - -/** - * g_pattern_match: (skip) - * @pspec: a #GPatternSpec - * @string_length: the length of @string (in bytes, i.e. strlen(), - * not g_utf8_strlen()) - * @string: the UTF-8 encoded string to match - * @string_reversed: (nullable): the reverse of @string or %NULL - * - * Matches a string against a compiled pattern. Passing the correct - * length of the string given is mandatory. The reversed string can be - * omitted by passing %NULL, this is more efficient if the reversed - * version of the string to be matched is not at hand, as - * g_pattern_match() will only construct it if the compiled pattern - * requires reverse matches. - * - * Note that, if the user code will (possibly) match a string against a - * multitude of patterns containing wildcards, chances are high that - * some patterns will require a reversed string. In this case, it's - * more efficient to provide the reversed string to avoid multiple - * constructions thereof in the various calls to g_pattern_match(). - * - * Note also that the reverse of a UTF-8 encoded string can in general - * not be obtained by g_strreverse(). This works only if the string - * does not contain any multibyte characters. GLib offers the - * g_utf8_strreverse() function to reverse UTF-8 encoded strings. - * - * Returns: %TRUE if @string matches @pspec - * Deprecated: 2.70: Use g_pattern_spec_match() instead - */ - - -/** - * g_pattern_match_simple: - * @pattern: the UTF-8 encoded pattern - * @string: the UTF-8 encoded string to match - * - * Matches a string against a pattern given as a string. If this - * function is to be called in a loop, it's more efficient to compile - * the pattern once with g_pattern_spec_new() and call - * g_pattern_match_string() repeatedly. - * - * Returns: %TRUE if @string matches @pspec - */ - - -/** - * g_pattern_match_string: (skip) - * @pspec: a #GPatternSpec - * @string: the UTF-8 encoded string to match - * - * Matches a string against a compiled pattern. If the string is to be - * matched against more than one pattern, consider using - * g_pattern_match() instead while supplying the reversed string. - * - * Returns: %TRUE if @string matches @pspec - * Deprecated: 2.70: Use g_pattern_spec_match_string() instead - */ - - -/** - * g_pattern_spec_copy: - * @pspec: a #GPatternSpec - * - * Copies @pspec in a new #GPatternSpec. - * - * Returns: (transfer full): a copy of @pspec. - * Since: 2.70 - */ - - -/** - * g_pattern_spec_equal: - * @pspec1: a #GPatternSpec - * @pspec2: another #GPatternSpec - * - * Compares two compiled pattern specs and returns whether they will - * match the same set of strings. - * - * Returns: Whether the compiled patterns are equal - */ - - -/** - * g_pattern_spec_free: - * @pspec: a #GPatternSpec - * - * Frees the memory allocated for the #GPatternSpec. - */ - - -/** - * g_pattern_spec_match: - * @pspec: a #GPatternSpec - * @string_length: the length of @string (in bytes, i.e. strlen(), - * not g_utf8_strlen()) - * @string: the UTF-8 encoded string to match - * @string_reversed: (nullable): the reverse of @string or %NULL - * - * Matches a string against a compiled pattern. Passing the correct - * length of the string given is mandatory. The reversed string can be - * omitted by passing %NULL, this is more efficient if the reversed - * version of the string to be matched is not at hand, as - * g_pattern_match() will only construct it if the compiled pattern - * requires reverse matches. - * - * Note that, if the user code will (possibly) match a string against a - * multitude of patterns containing wildcards, chances are high that - * some patterns will require a reversed string. In this case, it's - * more efficient to provide the reversed string to avoid multiple - * constructions thereof in the various calls to g_pattern_match(). - * - * Note also that the reverse of a UTF-8 encoded string can in general - * not be obtained by g_strreverse(). This works only if the string - * does not contain any multibyte characters. GLib offers the - * g_utf8_strreverse() function to reverse UTF-8 encoded strings. - * - * Returns: %TRUE if @string matches @pspec - * Since: 2.70 - */ - - -/** - * g_pattern_spec_match_string: - * @pspec: a #GPatternSpec - * @string: the UTF-8 encoded string to match - * - * Matches a string against a compiled pattern. If the string is to be - * matched against more than one pattern, consider using - * g_pattern_match() instead while supplying the reversed string. - * - * Returns: %TRUE if @string matches @pspec - * Since: 2.70 - */ - - -/** - * g_pattern_spec_new: - * @pattern: a zero-terminated UTF-8 encoded string - * - * Compiles a pattern to a #GPatternSpec. - * - * Returns: a newly-allocated #GPatternSpec - */ - - -/** - * g_pointer_bit_lock: - * @address: (not nullable): a pointer to a #gpointer-sized value - * @lock_bit: a bit value between 0 and 31 - * - * This is equivalent to g_bit_lock, but working on pointers (or other - * pointer-sized values). - * - * For portability reasons, you may only lock on the bottom 32 bits of - * the pointer. - * - * While @address has a `volatile` qualifier, this is a historical - * artifact and the argument passed to it should not be `volatile`. - * - * Since: 2.30 - */ - - -/** - * g_pointer_bit_trylock: - * @address: (not nullable): a pointer to a #gpointer-sized value - * @lock_bit: a bit value between 0 and 31 - * - * This is equivalent to g_bit_trylock(), but working on pointers (or - * other pointer-sized values). - * - * For portability reasons, you may only lock on the bottom 32 bits of - * the pointer. - * - * 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.30 - */ - - -/** - * g_pointer_bit_unlock: - * @address: (not nullable): a pointer to a #gpointer-sized value - * @lock_bit: a bit value between 0 and 31 - * - * This is equivalent to g_bit_unlock, but working on pointers (or other - * pointer-sized values). - * - * For portability reasons, you may only lock on the bottom 32 bits of - * the pointer. - * - * While @address has a `volatile` qualifier, this is a historical - * artifact and the argument passed to it should not be `volatile`. - * - * Since: 2.30 - */ - - -/** - * g_poll: - * @fds: file descriptors to poll - * @nfds: the number of file descriptors in @fds - * @timeout: amount of time to wait, in milliseconds, or -1 to wait forever - * - * Polls @fds, as with the poll() system call, but portably. (On - * systems that don't have poll(), it is emulated using select().) - * This is used internally by #GMainContext, but it can be called - * directly if you need to block until a file descriptor is ready, but - * don't want to run the full main loop. - * - * Each element of @fds is a #GPollFD describing a single file - * descriptor to poll. The @fd field indicates the file descriptor, - * and the @events field indicates the events to poll for. On return, - * the @revents fields will be filled with the events that actually - * occurred. - * - * On POSIX systems, the file descriptors in @fds can be any sort of - * file descriptor, but the situation is much more complicated on - * Windows. If you need to use g_poll() in code that has to run on - * Windows, the easiest solution is to construct all of your - * #GPollFDs with g_io_channel_win32_make_pollfd(). - * - * Returns: the number of entries in @fds whose @revents fields - * were filled in, or 0 if the operation timed out, or -1 on error or - * if the call was interrupted. - * Since: 2.20 - */ - - -/** - * g_prefix_error: - * @err: (inout) (optional) (nullable): a return location for a #GError - * @format: printf()-style format string - * @...: arguments to @format - * - * Formats a string according to @format and prefix it to an existing - * error message. If @err is %NULL (ie: no error variable) then do - * nothing. - * - * If *@err is %NULL (ie: an error variable is present but there is no - * error condition) then also do nothing. - * - * Since: 2.16 - */ - - -/** - * g_prefix_error_literal: - * @err: (allow-none): a return location for a #GError, or %NULL - * @prefix: string to prefix @err with - * - * Prefixes @prefix to an existing error message. If @err or *@err is - * %NULL (i.e.: no error variable) then do nothing. - * - * Since: 2.70 - */ - - -/** - * g_print: - * @format: the message format. See the printf() documentation - * @...: the parameters to insert into the format string - * - * Outputs a formatted message via the print handler. - * The default print handler simply outputs the message to stdout, without - * appending a trailing new-line character. Typically, @format should end with - * its own new-line character. - * - * g_print() should not be used from within libraries for debugging - * messages, since it may be redirected by applications to special - * purpose message windows or even files. Instead, libraries should - * use g_log(), g_log_structured(), or the convenience macros g_message(), - * g_warning() and g_error(). - */ - - -/** - * g_printerr: - * @format: the message format. See the printf() documentation - * @...: the parameters to insert into the format string - * - * Outputs a formatted message via the error message handler. - * The default handler simply outputs the message to stderr, without appending - * a trailing new-line character. Typically, @format should end with its own - * new-line character. - * - * g_printerr() should not be used from within libraries. - * Instead g_log() or g_log_structured() should be used, or the convenience - * macros g_message(), g_warning() and g_error(). - */ - - -/** - * g_printf: - * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] - * @...: the arguments to insert in the output. - * - * An implementation of the standard printf() function which supports - * positional parameters, as specified in the Single Unix Specification. - * - * As with the standard printf(), this does not automatically append a trailing - * new-line character to the message, so typically @format should end with its - * own new-line character. - * - * `glib/gprintf.h` must be explicitly included in order to use this function. - * - * Returns: the number of bytes printed. - * Since: 2.2 - */ - - -/** - * g_printf_string_upper_bound: - * @format: the format string. See the printf() documentation - * @args: the parameters to be inserted into the format string - * - * Calculates the maximum space needed to store the output - * of the sprintf() function. - * - * Returns: the maximum space needed to store the formatted string - */ - - -/** - * g_private_get: - * @key: a #GPrivate - * - * Returns the current value of the thread local variable @key. - * - * If the value has not yet been set in this thread, %NULL is returned. - * Values are never copied between threads (when a new thread is - * created, for example). - * - * Returns: the thread-local value - */ - - -/** - * g_private_replace: - * @key: a #GPrivate - * @value: the new value - * - * Sets the thread local variable @key to have the value @value in the - * current thread. - * - * This function differs from g_private_set() in the following way: if - * the previous value was non-%NULL then the #GDestroyNotify handler for - * @key is run on it. - * - * Since: 2.32 - */ - - -/** - * g_private_set: - * @key: a #GPrivate - * @value: the new value - * - * Sets the thread local variable @key to have the value @value in the - * current thread. - * - * This function differs from g_private_replace() in the following way: - * the #GDestroyNotify for @key is not called on the old value. - */ - - -/** - * g_propagate_error: - * @dest: (out callee-allocates) (optional) (nullable): error return location - * @src: (transfer full): error to move into the return location - * - * If @dest is %NULL, free @src; otherwise, moves @src into *@dest. - * The error variable @dest points to must be %NULL. - * - * @src must be non-%NULL. - * - * Note that @src is no longer valid after this call. If you want - * to keep using the same GError*, you need to set it to %NULL - * after calling this function on it. - */ - - -/** - * g_propagate_prefixed_error: - * @dest: error return location - * @src: error to move into the return location - * @format: printf()-style format string - * @...: arguments to @format - * - * If @dest is %NULL, free @src; otherwise, moves @src into *@dest. - * *@dest must be %NULL. After the move, add a prefix as with - * g_prefix_error(). - * - * Since: 2.16 - */ - - -/** - * g_ptr_array_add: - * @array: a #GPtrArray - * @data: the pointer to add - * - * Adds a pointer to the end of the pointer array. The array will grow - * in size automatically if necessary. - */ - - -/** - * g_ptr_array_copy: - * @array: #GPtrArray to duplicate - * @func: (nullable): a copy function used to copy every element in the array - * @user_data: user data passed to the copy function @func, or %NULL - * - * Makes a full (deep) copy of a #GPtrArray. - * - * @func, as a #GCopyFunc, takes two arguments, the data to be copied - * and a @user_data pointer. On common processor architectures, it's safe to - * pass %NULL as @user_data if the copy function takes only one argument. You - * may get compiler warnings from this though if compiling with GCC’s - * `-Wcast-function-type` warning. - * - * If @func is %NULL, then only the pointers (and not what they are - * pointing to) are copied to the new #GPtrArray. - * - * The copy of @array will have the same #GDestroyNotify for its elements as - * @array. - * - * Returns: (transfer full): a deep copy of the initial #GPtrArray. - * Since: 2.62 - */ - - -/** - * g_ptr_array_extend: - * @array_to_extend: a #GPtrArray. - * @array: (transfer none): a #GPtrArray to add to the end of @array_to_extend. - * @func: (nullable): a copy function used to copy every element in the array - * @user_data: user data passed to the copy function @func, or %NULL - * - * Adds all pointers of @array to the end of the array @array_to_extend. - * The array will grow in size automatically if needed. @array_to_extend is - * modified in-place. - * - * @func, as a #GCopyFunc, takes two arguments, the data to be copied - * and a @user_data pointer. On common processor architectures, it's safe to - * pass %NULL as @user_data if the copy function takes only one argument. You - * may get compiler warnings from this though if compiling with GCC’s - * `-Wcast-function-type` warning. - * - * If @func is %NULL, then only the pointers (and not what they are - * pointing to) are copied to the new #GPtrArray. - * - * Since: 2.62 - */ - - -/** - * g_ptr_array_extend_and_steal: - * @array_to_extend: (transfer none): a #GPtrArray. - * @array: (transfer container): a #GPtrArray to add to the end of - * @array_to_extend. - * - * Adds all the pointers in @array to the end of @array_to_extend, transferring - * ownership of each element from @array to @array_to_extend and modifying - * @array_to_extend in-place. @array is then freed. - * - * As with g_ptr_array_free(), @array will be destroyed if its reference count - * is 1. If its reference count is higher, it will be decremented and the - * length of @array set to zero. - * - * Since: 2.62 - */ - - -/** - * g_ptr_array_find: (skip) - * @haystack: pointer array to be searched - * @needle: pointer to look for - * @index_: (optional) (out): return location for the index of - * the element, if found - * - * Checks whether @needle exists in @haystack. If the element is found, %TRUE is - * returned and the element’s index is returned in @index_ (if non-%NULL). - * Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists - * multiple times in @haystack, the index of the first instance is returned. - * - * This does pointer comparisons only. If you want to use more complex equality - * checks, such as string comparisons, use g_ptr_array_find_with_equal_func(). - * - * Returns: %TRUE if @needle is one of the elements of @haystack - * Since: 2.54 - */ - - -/** - * g_ptr_array_find_with_equal_func: (skip) - * @haystack: pointer array to be searched - * @needle: pointer to look for - * @equal_func: (nullable): the function to call for each element, which should - * return %TRUE when the desired element is found; or %NULL to use pointer - * equality - * @index_: (optional) (out): return location for the index of - * the element, if found - * - * Checks whether @needle exists in @haystack, using the given @equal_func. - * If the element is found, %TRUE is returned and the element’s index is - * returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_ - * is undefined. If @needle exists multiple times in @haystack, the index of - * the first instance is returned. - * - * @equal_func is called with the element from the array as its first parameter, - * and @needle as its second parameter. If @equal_func is %NULL, pointer - * equality is used. - * - * Returns: %TRUE if @needle is one of the elements of @haystack - * Since: 2.54 - */ - - -/** - * g_ptr_array_foreach: - * @array: a #GPtrArray - * @func: the function to call for each array element - * @user_data: user data to pass to the function - * - * Calls a function for each element of a #GPtrArray. @func must not - * add elements to or remove elements from the array. - * - * Since: 2.4 - */ - - -/** - * g_ptr_array_free: - * @array: a #GPtrArray - * @free_seg: if %TRUE the actual pointer array is freed as well - * - * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE - * it frees the memory block holding the elements as well. Pass %FALSE - * if you want to free the #GPtrArray wrapper but preserve the - * underlying array for use elsewhere. If the reference count of @array - * is greater than one, the #GPtrArray 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 #GDestroyNotify - * function has been set for @array. - * - * This function is not thread-safe. If using a #GPtrArray from multiple - * threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref() - * functions. - * - * Returns: (transfer full) (nullable): the pointer array if @free_seg is - * %FALSE, otherwise %NULL. The pointer array should be freed using g_free(). - */ - - -/** - * g_ptr_array_index: - * @array: a #GPtrArray - * @index_: the index of the pointer to return - * - * Returns the pointer at the given index of the pointer array. - * - * This does not perform bounds checking on the given @index_, - * so you are responsible for checking it against the array length. - * - * Returns: the pointer at the given index - */ - - -/** - * g_ptr_array_insert: - * @array: a #GPtrArray - * @index_: the index to place the new element at, or -1 to append - * @data: the pointer to add. - * - * Inserts an element into the pointer array at the given index. The - * array will grow in size automatically if necessary. - * - * Since: 2.40 - */ - - -/** - * g_ptr_array_new: - * - * Creates a new #GPtrArray with a reference count of 1. - * - * Returns: the new #GPtrArray - */ - - -/** - * g_ptr_array_new_full: - * @reserved_size: number of pointers preallocated - * @element_free_func: (nullable): A function to free elements with - * destroy @array or %NULL - * - * Creates a new #GPtrArray with @reserved_size pointers preallocated - * and a reference count of 1. This avoids frequent reallocation, if - * you are going to add many pointers to the array. Note however that - * the size of the array is still 0. It also set @element_free_func - * for freeing each element when the array is destroyed either via - * g_ptr_array_unref(), when g_ptr_array_free() is called with - * @free_segment set to %TRUE or when removing elements. - * - * Returns: A new #GPtrArray - * Since: 2.30 - */ - - -/** - * g_ptr_array_new_with_free_func: - * @element_free_func: (nullable): A function to free elements with - * destroy @array or %NULL - * - * Creates a new #GPtrArray with a reference count of 1 and use - * @element_free_func for freeing each element when the array is destroyed - * either via g_ptr_array_unref(), when g_ptr_array_free() is called with - * @free_segment set to %TRUE or when removing elements. - * - * Returns: A new #GPtrArray - * Since: 2.22 - */ - - -/** - * g_ptr_array_ref: - * @array: a #GPtrArray - * - * 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 #GPtrArray - * Since: 2.22 - */ - - -/** - * g_ptr_array_remove: - * @array: a #GPtrArray - * @data: the pointer to remove - * - * Removes the first occurrence of the given pointer from the pointer - * array. The following elements are moved down one place. If @array - * has a non-%NULL #GDestroyNotify function it is called for the - * removed element. - * - * It returns %TRUE if the pointer was removed, or %FALSE if the - * pointer was not found. - * - * Returns: %TRUE if the pointer is removed, %FALSE if the pointer - * is not found in the array - */ - - -/** - * g_ptr_array_remove_fast: - * @array: a #GPtrArray - * @data: the pointer to remove - * - * Removes the first occurrence of the given pointer from the pointer - * array. The last element in the array is used to fill in the space, - * so this function does not preserve the order of the array. But it - * is faster than g_ptr_array_remove(). If @array has a non-%NULL - * #GDestroyNotify function it is called for the removed element. - * - * It returns %TRUE if the pointer was removed, or %FALSE if the - * pointer was not found. - * - * Returns: %TRUE if the pointer was found in the array - */ - - -/** - * g_ptr_array_remove_index: - * @array: a #GPtrArray - * @index_: the index of the pointer to remove - * - * Removes the pointer at the given index from the pointer array. - * The following elements are moved down one place. If @array has - * a non-%NULL #GDestroyNotify function it is called for the removed - * element. If so, the return value from this function will potentially point - * to freed memory (depending on the #GDestroyNotify implementation). - * - * Returns: (nullable): the pointer which was removed - */ - - -/** - * g_ptr_array_remove_index_fast: - * @array: a #GPtrArray - * @index_: the index of the pointer to remove - * - * Removes the pointer at the given index from the pointer array. - * The last element in the array is used to fill in the space, so - * this function does not preserve the order of the array. But it - * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL - * #GDestroyNotify function it is called for the removed element. If so, the - * return value from this function will potentially point to freed memory - * (depending on the #GDestroyNotify implementation). - * - * Returns: (nullable): the pointer which was removed - */ - - -/** - * g_ptr_array_remove_range: - * @array: a @GPtrArray - * @index_: the index of the first pointer to remove - * @length: the number of pointers to remove - * - * Removes the given number of pointers starting at the given index - * from a #GPtrArray. The following elements are moved to close the - * gap. If @array has a non-%NULL #GDestroyNotify function it is - * called for the removed elements. - * - * Returns: the @array - * Since: 2.4 - */ - - -/** - * g_ptr_array_set_free_func: - * @array: A #GPtrArray - * @element_free_func: (nullable): A function to free elements with - * destroy @array or %NULL - * - * Sets a function for freeing each element when @array is destroyed - * either via g_ptr_array_unref(), when g_ptr_array_free() is called - * with @free_segment set to %TRUE or when removing elements. - * - * Since: 2.22 - */ - - -/** - * g_ptr_array_set_size: - * @array: a #GPtrArray - * @length: the new length of the pointer array - * - * Sets the size of the array. When making the array larger, - * newly-added elements will be set to %NULL. When making it smaller, - * if @array has a non-%NULL #GDestroyNotify function then it will be - * called for the removed elements. - */ - - -/** - * g_ptr_array_sized_new: - * @reserved_size: number of pointers preallocated - * - * Creates a new #GPtrArray with @reserved_size pointers preallocated - * and a reference count of 1. This avoids frequent reallocation, if - * you are going to add many pointers to the array. Note however that - * the size of the array is still 0. - * - * Returns: the new #GPtrArray - */ - - -/** - * g_ptr_array_sort: - * @array: a #GPtrArray - * @compare_func: comparison function - * - * Sorts the 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 irst arg is - * greater than second arg). - * - * Note that the comparison function for g_ptr_array_sort() doesn't - * take the pointers from the array as arguments, it takes pointers to - * the pointers in the array. Here is a full example of usage: - * - * |[<!-- language="C" --> - * typedef struct - * { - * gchar *name; - * gint size; - * } FileListEntry; - * - * static gint - * sort_filelist (gconstpointer a, gconstpointer b) - * { - * const FileListEntry *entry1 = *((FileListEntry **) a); - * const FileListEntry *entry2 = *((FileListEntry **) b); - * - * return g_ascii_strcasecmp (entry1->name, entry2->name); - * } - * - * … - * g_autoptr (GPtrArray) file_list = NULL; - * - * // initialize file_list array and load with many FileListEntry entries - * ... - * // now sort it with - * g_ptr_array_sort (file_list, sort_filelist); - * ]| - * - * This is guaranteed to be a stable sort since version 2.32. - */ - - -/** - * g_ptr_array_sort_with_data: - * @array: a #GPtrArray - * @compare_func: comparison function - * @user_data: data to pass to @compare_func - * - * Like g_ptr_array_sort(), but the comparison function has an extra - * user data argument. - * - * Note that the comparison function for g_ptr_array_sort_with_data() - * doesn't take the pointers from the array as arguments, it takes - * pointers to the pointers in the array. Here is a full example of use: - * - * |[<!-- language="C" --> - * typedef enum { SORT_NAME, SORT_SIZE } SortMode; - * - * typedef struct - * { - * gchar *name; - * gint size; - * } FileListEntry; - * - * static gint - * sort_filelist (gconstpointer a, gconstpointer b, gpointer user_data) - * { - * gint order; - * const SortMode sort_mode = GPOINTER_TO_INT (user_data); - * const FileListEntry *entry1 = *((FileListEntry **) a); - * const FileListEntry *entry2 = *((FileListEntry **) b); - * - * switch (sort_mode) - * { - * case SORT_NAME: - * order = g_ascii_strcasecmp (entry1->name, entry2->name); - * break; - * case SORT_SIZE: - * order = entry1->size - entry2->size; - * break; - * default: - * order = 0; - * break; - * } - * return order; - * } - * - * ... - * g_autoptr (GPtrArray) file_list = NULL; - * SortMode sort_mode; - * - * // initialize file_list array and load with many FileListEntry entries - * ... - * // now sort it with - * sort_mode = SORT_NAME; - * g_ptr_array_sort_with_data (file_list, - * sort_filelist, - * GINT_TO_POINTER (sort_mode)); - * ]| - * - * This is guaranteed to be a stable sort since version 2.32. - */ - - -/** - * g_ptr_array_steal: - * @array: a #GPtrArray. - * @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. - * - * Even if set, the #GDestroyNotify function will never be called - * on the current contents of the array and the caller is - * responsible for freeing the array elements. - * - * An example of use: - * |[<!-- language="C" --> - * g_autoptr(GPtrArray) chunk_buffer = g_ptr_array_new_with_free_func (g_bytes_unref); - * - * // Some part of your application appends a number of chunks to the pointer array. - * g_ptr_array_add (chunk_buffer, g_bytes_new_static ("hello", 5)); - * g_ptr_array_add (chunk_buffer, g_bytes_new_static ("world", 5)); - * - * … - * - * // Periodically, the chunks need to be sent as an array-and-length to some - * // other part of the program. - * GBytes **chunks; - * gsize n_chunks; - * - * chunks = g_ptr_array_steal (chunk_buffer, &n_chunks); - * for (gsize i = 0; i < n_chunks; i++) - * { - * // Do something with each chunk here, and then free them, since - * // g_ptr_array_steal() transfers ownership of all the elements and the - * // array to the caller. - * … - * - * g_bytes_unref (chunks[i]); - * } - * - * g_free (chunks); - * - * // After calling g_ptr_array_steal(), the pointer array can be reused for the - * // next set of chunks. - * g_assert (chunk_buffer->len == 0); - * ]| - * - * Returns: (transfer full): the element data, which should be - * freed using g_free(). - * Since: 2.64 - */ - - -/** - * g_ptr_array_steal_index: - * @array: a #GPtrArray - * @index_: the index of the pointer to steal - * - * Removes the pointer at the given index from the pointer array. - * The following elements are moved down one place. The #GDestroyNotify for - * @array is *not* called on the removed element; ownership is transferred to - * the caller of this function. - * - * Returns: (transfer full) (nullable): the pointer which was removed - * Since: 2.58 - */ - - -/** - * g_ptr_array_steal_index_fast: - * @array: a #GPtrArray - * @index_: the index of the pointer to steal - * - * Removes the pointer at the given index from the pointer array. - * The last element in the array is used to fill in the space, so - * this function does not preserve the order of the array. But it - * is faster than g_ptr_array_steal_index(). The #GDestroyNotify for @array is - * *not* called on the removed element; ownership is transferred to the caller - * of this function. - * - * Returns: (transfer full) (nullable): the pointer which was removed - * Since: 2.58 - */ - - -/** - * g_ptr_array_unref: - * @array: A #GPtrArray - * - * Atomically decrements the reference count of @array by one. If the - * reference count drops to 0, the effect is the same as calling - * g_ptr_array_free() with @free_segment set to %TRUE. This function - * is thread-safe and may be called from any thread. - * - * Since: 2.22 - */ - - -/** - * g_qsort_with_data: - * @pbase: (not nullable): start of array to sort - * @total_elems: elements in the array - * @size: size of each element - * @compare_func: function to compare elements - * @user_data: data to pass to @compare_func - * - * This is just like the standard C qsort() function, but - * the comparison routine accepts a user data argument. - * - * This is guaranteed to be a stable sort since version 2.32. - */ - - -/** - * g_quark_from_static_string: - * @string: (nullable): a string - * - * Gets the #GQuark identifying the given (static) string. If the - * string does not currently have an associated #GQuark, a new #GQuark - * is created, linked to the given string. - * - * Note that this function is identical to g_quark_from_string() except - * that if a new #GQuark is created the string itself is used rather - * than a copy. This saves memory, but can only be used if the string - * will continue to exist until the program terminates. It can be used - * with statically allocated strings in the main program, but not with - * statically allocated memory in dynamically loaded modules, if you - * expect to ever unload the module again (e.g. do not use this - * function in GTK+ theme engines). - * - * This function must not be used before library constructors have finished - * running. In particular, this means it cannot be used to initialize global - * variables in C++. - * - * Returns: the #GQuark identifying the string, or 0 if @string is %NULL - */ - - -/** - * g_quark_from_string: - * @string: (nullable): a string - * - * Gets the #GQuark identifying the given string. If the string does - * not currently have an associated #GQuark, a new #GQuark is created, - * using a copy of the string. - * - * This function must not be used before library constructors have finished - * running. In particular, this means it cannot be used to initialize global - * variables in C++. - * - * Returns: the #GQuark identifying the string, or 0 if @string is %NULL - */ - - -/** - * g_quark_to_string: - * @quark: a #GQuark. - * - * Gets the string associated with the given #GQuark. - * - * Returns: the string associated with the #GQuark - */ - - -/** - * g_quark_try_string: - * @string: (nullable): a string - * - * Gets the #GQuark associated with the given string, or 0 if string is - * %NULL or it has no associated #GQuark. - * - * If you want the GQuark to be created if it doesn't already exist, - * use g_quark_from_string() or g_quark_from_static_string(). - * - * This function must not be used before library constructors have finished - * running. - * - * Returns: the #GQuark associated with the string, or 0 if @string is - * %NULL or there is no #GQuark associated with it - */ - - -/** - * g_queue_clear: - * @queue: a #GQueue - * - * Removes all the elements in @queue. If queue elements contain - * dynamically-allocated memory, they should be freed first. - * - * Since: 2.14 - */ - - -/** - * g_queue_clear_full: - * @queue: a pointer to a #GQueue - * @free_func: (nullable): the function to be called to free memory allocated - * - * Convenience method, which frees all the memory used by a #GQueue, - * and calls the provided @free_func on each item in the #GQueue. - * - * Since: 2.60 - */ - - -/** - * g_queue_copy: - * @queue: a #GQueue - * - * Copies a @queue. Note that is a shallow copy. If the elements in the - * queue consist of pointers to data, the pointers are copied, but the - * actual data is not. - * - * Returns: a copy of @queue - * Since: 2.4 - */ - - -/** - * g_queue_delete_link: - * @queue: a #GQueue - * @link_: a #GList link that must be part of @queue - * - * Removes @link_ from @queue and frees it. - * - * @link_ must be part of @queue. - * - * Since: 2.4 - */ - - -/** - * g_queue_find: - * @queue: a #GQueue - * @data: data to find - * - * Finds the first link in @queue which contains @data. - * - * Returns: the first link in @queue which contains @data - * Since: 2.4 - */ - - -/** - * g_queue_find_custom: - * @queue: a #GQueue - * @data: user data passed to @func - * @func: a #GCompareFunc to call for each element. It should return 0 - * when the desired element is found - * - * Finds an element in a #GQueue, using a supplied function to find the - * desired element. It iterates over the queue, calling the given function - * which should return 0 when the desired element is found. The function - * takes two gconstpointer arguments, the #GQueue element's data as the - * first argument and the given user data as the second argument. - * - * Returns: the found link, or %NULL if it wasn't found - * Since: 2.4 - */ - - -/** - * g_queue_foreach: - * @queue: a #GQueue - * @func: the function to call for each element's data - * @user_data: user data to pass to @func - * - * Calls @func for each element in the queue passing @user_data to the - * function. - * - * It is safe for @func to remove the element from @queue, but it must - * not modify any part of the queue after that element. - * - * Since: 2.4 - */ - - -/** - * g_queue_free: - * @queue: a #GQueue - * - * Frees the memory allocated for the #GQueue. Only call this function - * if @queue was created with g_queue_new(). If queue elements contain - * dynamically-allocated memory, they should be freed first. - * - * If queue elements contain dynamically-allocated memory, you should - * either use g_queue_free_full() or free them manually first. - */ - - -/** - * g_queue_free_full: - * @queue: a pointer to a #GQueue - * @free_func: the function to be called to free each element's data - * - * Convenience method, which frees all the memory used by a #GQueue, - * and calls the specified destroy function on every element's data. - * - * @free_func should not modify the queue (eg, by removing the freed - * element from it). - * - * Since: 2.32 - */ - - -/** - * g_queue_get_length: - * @queue: a #GQueue - * - * Returns the number of items in @queue. - * - * Returns: the number of items in @queue - * Since: 2.4 - */ - - -/** - * g_queue_index: - * @queue: a #GQueue - * @data: the data to find - * - * Returns the position of the first element in @queue which contains @data. - * - * Returns: the position of the first element in @queue which - * contains @data, or -1 if no element in @queue contains @data - * Since: 2.4 - */ - - -/** - * g_queue_init: - * @queue: an uninitialized #GQueue - * - * A statically-allocated #GQueue must be initialized with this function - * before it can be used. Alternatively you can initialize it with - * #G_QUEUE_INIT. It is not necessary to initialize queues created with - * g_queue_new(). - * - * Since: 2.14 - */ - - -/** - * g_queue_insert_after: - * @queue: a #GQueue - * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to - * push at the head of the queue. - * @data: the data to insert - * - * Inserts @data into @queue after @sibling. - * - * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the - * data at the head of the queue. - * - * Since: 2.4 - */ - - -/** - * g_queue_insert_after_link: - * @queue: a #GQueue - * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to - * push at the head of the queue. - * @link_: a #GList link to insert which must not be part of any other list. - * - * Inserts @link_ into @queue after @sibling. - * - * @sibling must be part of @queue. - * - * Since: 2.62 - */ - - -/** - * g_queue_insert_before: - * @queue: a #GQueue - * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to - * push at the tail of the queue. - * @data: the data to insert - * - * Inserts @data into @queue before @sibling. - * - * @sibling must be part of @queue. Since GLib 2.44 a %NULL sibling pushes the - * data at the tail of the queue. - * - * Since: 2.4 - */ - - -/** - * g_queue_insert_before_link: - * @queue: a #GQueue - * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to - * push at the tail of the queue. - * @link_: a #GList link to insert which must not be part of any other list. - * - * Inserts @link_ into @queue before @sibling. - * - * @sibling must be part of @queue. - * - * Since: 2.62 - */ - - -/** - * g_queue_insert_sorted: - * @queue: a #GQueue - * @data: the data to insert - * @func: the #GCompareDataFunc used to compare elements in the queue. It is - * called with two elements of the @queue and @user_data. It should - * return 0 if the elements are equal, a negative value if the first - * element comes before the second, and a positive value if the second - * element comes before the first. - * @user_data: user data passed to @func - * - * Inserts @data into @queue using @func to determine the new position. - * - * Since: 2.4 - */ - - -/** - * g_queue_is_empty: - * @queue: a #GQueue. - * - * Returns %TRUE if the queue is empty. - * - * Returns: %TRUE if the queue is empty - */ - - -/** - * g_queue_link_index: - * @queue: a #GQueue - * @link_: a #GList link - * - * Returns the position of @link_ in @queue. - * - * Returns: the position of @link_, or -1 if the link is - * not part of @queue - * Since: 2.4 - */ - - -/** - * g_queue_new: - * - * Creates a new #GQueue. - * - * Returns: a newly allocated #GQueue - */ - - -/** - * g_queue_peek_head: - * @queue: a #GQueue - * - * Returns the first element of the queue. - * - * Returns: the data of the first element in the queue, or %NULL - * if the queue is empty - */ - - -/** - * g_queue_peek_head_link: - * @queue: a #GQueue - * - * Returns the first link in @queue. - * - * Returns: the first link in @queue, or %NULL if @queue is empty - * Since: 2.4 - */ - - -/** - * g_queue_peek_nth: - * @queue: a #GQueue - * @n: the position of the element - * - * Returns the @n'th element of @queue. - * - * Returns: the data for the @n'th element of @queue, - * or %NULL if @n is off the end of @queue - * Since: 2.4 - */ - - -/** - * g_queue_peek_nth_link: - * @queue: a #GQueue - * @n: the position of the link - * - * Returns the link at the given position - * - * Returns: the link at the @n'th position, or %NULL - * if @n is off the end of the list - * Since: 2.4 - */ - - -/** - * g_queue_peek_tail: - * @queue: a #GQueue - * - * Returns the last element of the queue. - * - * Returns: the data of the last element in the queue, or %NULL - * if the queue is empty - */ - - -/** - * g_queue_peek_tail_link: - * @queue: a #GQueue - * - * Returns the last link in @queue. - * - * Returns: the last link in @queue, or %NULL if @queue is empty - * Since: 2.4 - */ - - -/** - * g_queue_pop_head: - * @queue: a #GQueue - * - * Removes the first element of the queue and returns its data. - * - * Returns: the data of the first element in the queue, or %NULL - * if the queue is empty - */ - - -/** - * g_queue_pop_head_link: - * @queue: a #GQueue - * - * Removes and returns the first element of the queue. - * - * Returns: the #GList element at the head of the queue, or %NULL - * if the queue is empty - */ - - -/** - * g_queue_pop_nth: - * @queue: a #GQueue - * @n: the position of the element - * - * Removes the @n'th element of @queue and returns its data. - * - * Returns: the element's data, or %NULL if @n is off the end of @queue - * Since: 2.4 - */ - - -/** - * g_queue_pop_nth_link: - * @queue: a #GQueue - * @n: the link's position - * - * Removes and returns the link at the given position. - * - * Returns: the @n'th link, or %NULL if @n is off the end of @queue - * Since: 2.4 - */ - - -/** - * g_queue_pop_tail: - * @queue: a #GQueue - * - * Removes the last element of the queue and returns its data. - * - * Returns: the data of the last element in the queue, or %NULL - * if the queue is empty - */ - - -/** - * g_queue_pop_tail_link: - * @queue: a #GQueue - * - * Removes and returns the last element of the queue. - * - * Returns: the #GList element at the tail of the queue, or %NULL - * if the queue is empty - */ - - -/** - * g_queue_push_head: - * @queue: a #GQueue. - * @data: the data for the new element. - * - * Adds a new element at the head of the queue. - */ - - -/** - * g_queue_push_head_link: - * @queue: a #GQueue - * @link_: a single #GList element, not a list with more than one element - * - * Adds a new element at the head of the queue. - */ - - -/** - * g_queue_push_nth: - * @queue: a #GQueue - * @data: the data for the new element - * @n: the position to insert the new element. If @n is negative or - * larger than the number of elements in the @queue, the element is - * added to the end of the queue. - * - * Inserts a new element into @queue at the given position. - * - * Since: 2.4 - */ - - -/** - * g_queue_push_nth_link: - * @queue: a #GQueue - * @n: the position to insert the link. If this is negative or larger than - * the number of elements in @queue, the link is added to the end of - * @queue. - * @link_: the link to add to @queue - * - * Inserts @link into @queue at the given position. - * - * Since: 2.4 - */ - - -/** - * g_queue_push_tail: - * @queue: a #GQueue - * @data: the data for the new element - * - * Adds a new element at the tail of the queue. - */ - - -/** - * g_queue_push_tail_link: - * @queue: a #GQueue - * @link_: a single #GList element, not a list with more than one element - * - * Adds a new element at the tail of the queue. - */ - - -/** - * g_queue_remove: - * @queue: a #GQueue - * @data: the data to remove - * - * Removes the first element in @queue that contains @data. - * - * Returns: %TRUE if @data was found and removed from @queue - * Since: 2.4 - */ - - -/** - * g_queue_remove_all: - * @queue: a #GQueue - * @data: the data to remove - * - * Remove all elements whose data equals @data from @queue. - * - * Returns: the number of elements removed from @queue - * Since: 2.4 - */ - - -/** - * g_queue_reverse: - * @queue: a #GQueue - * - * Reverses the order of the items in @queue. - * - * Since: 2.4 - */ - - -/** - * g_queue_sort: - * @queue: a #GQueue - * @compare_func: the #GCompareDataFunc used to sort @queue. This function - * is passed two elements of the queue and should return 0 if they are - * equal, a negative value if the first comes before the second, and - * a positive value if the second comes before the first. - * @user_data: user data passed to @compare_func - * - * Sorts @queue using @compare_func. - * - * Since: 2.4 - */ - - -/** - * g_queue_unlink: - * @queue: a #GQueue - * @link_: a #GList link that must be part of @queue - * - * Unlinks @link_ so that it will no longer be part of @queue. - * The link is not freed. - * - * @link_ must be part of @queue. - * - * Since: 2.4 - */ - - -/** - * g_rand_boolean: - * @rand_: a #GRand - * - * Returns a random #gboolean from @rand_. - * This corresponds to an unbiased coin toss. - * - * Returns: a random #gboolean - */ - - -/** - * g_rand_copy: - * @rand_: a #GRand - * - * Copies a #GRand into a new one with the same exact state as before. - * This way you can take a snapshot of the random number generator for - * replaying later. - * - * Returns: the new #GRand - * Since: 2.4 - */ - - -/** - * g_rand_double: - * @rand_: a #GRand - * - * Returns the next random #gdouble from @rand_ equally distributed over - * the range [0..1). - * - * Returns: a random number - */ - - -/** - * g_rand_double_range: - * @rand_: a #GRand - * @begin: lower closed bound of the interval - * @end: upper open bound of the interval - * - * Returns the next random #gdouble from @rand_ equally distributed over - * the range [@begin..@end). - * - * Returns: a random number - */ - - -/** - * g_rand_free: - * @rand_: a #GRand - * - * Frees the memory allocated for the #GRand. - */ - - -/** - * g_rand_int: - * @rand_: a #GRand - * - * Returns the next random #guint32 from @rand_ equally distributed over - * the range [0..2^32-1]. - * - * Returns: a random number - */ - - -/** - * g_rand_int_range: - * @rand_: a #GRand - * @begin: lower closed bound of the interval - * @end: upper open bound of the interval - * - * Returns the next random #gint32 from @rand_ equally distributed over - * the range [@begin..@end-1]. - * - * Returns: a random number - */ - - -/** - * g_rand_new: - * - * Creates a new random number generator initialized with a seed taken - * either from `/dev/urandom` (if existing) or from the current time - * (as a fallback). - * - * On Windows, the seed is taken from rand_s(). - * - * Returns: the new #GRand - */ - - -/** - * g_rand_new_with_seed: - * @seed: a value to initialize the random number generator - * - * Creates a new random number generator initialized with @seed. - * - * Returns: the new #GRand - */ - - -/** - * g_rand_new_with_seed_array: - * @seed: an array of seeds to initialize the random number generator - * @seed_length: an array of seeds to initialize the random number - * generator - * - * Creates a new random number generator initialized with @seed. - * - * Returns: the new #GRand - * Since: 2.4 - */ - - -/** - * g_rand_set_seed: - * @rand_: a #GRand - * @seed: a value to reinitialize the random number generator - * - * Sets the seed for the random number generator #GRand to @seed. - */ - - -/** - * g_rand_set_seed_array: - * @rand_: a #GRand - * @seed: array to initialize with - * @seed_length: length of array - * - * Initializes the random number generator by an array of longs. - * Array can be of arbitrary size, though only the first 624 values - * are taken. This function is useful if you have many low entropy - * seeds, or if you require more then 32 bits of actual entropy for - * your application. - * - * Since: 2.4 - */ - - -/** - * g_random_boolean: - * - * Returns a random #gboolean. - * This corresponds to an unbiased coin toss. - * - * Returns: a random #gboolean - */ - - -/** - * g_random_double: - * - * Returns a random #gdouble equally distributed over the range [0..1). - * - * Returns: a random number - */ - - -/** - * g_random_double_range: - * @begin: lower closed bound of the interval - * @end: upper open bound of the interval - * - * Returns a random #gdouble equally distributed over the range - * [@begin..@end). - * - * Returns: a random number - */ - - -/** - * g_random_int: - * - * Return a random #guint32 equally distributed over the range - * [0..2^32-1]. - * - * Returns: a random number - */ - - -/** - * g_random_int_range: - * @begin: lower closed bound of the interval - * @end: upper open bound of the interval - * - * Returns a random #gint32 equally distributed over the range - * [@begin..@end-1]. - * - * Returns: a random number - */ - - -/** - * g_random_set_seed: - * @seed: a value to reinitialize the global random number generator - * - * Sets the seed for the global random number generator, which is used - * by the g_random_* functions, to @seed. - */ - - -/** - * g_rc_box_acquire: - * @mem_block: (not nullable): a pointer to reference counted data - * - * 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_rc_box_alloc: - * @block_size: the size of the allocation, must be greater than 0 - * - * Allocates @block_size bytes of memory, and adds 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_rc_box_alloc0: - * @block_size: the size of the allocation, must be greater than 0 - * - * Allocates @block_size bytes of memory, and adds 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_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 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_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_rc_box_new: - * @type: the type to allocate, typically a structure name - * - * A convenience macro to allocate reference counted data with - * the size of the given @type. - * - * This macro calls g_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_rc_box_new0: - * @type: the type to allocate, typically a structure name - * - * A convenience macro to allocate reference counted data with - * the size of the given @type, and set its contents to zero. - * - * This macro calls g_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_rc_box_release: - * @mem_block: (transfer full) (not nullable): a pointer to reference counted data - * - * 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_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 - * - * 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_realloc: - * @mem: (nullable): the memory to reallocate - * @n_bytes: new size of the memory in bytes - * - * Reallocates the memory pointed to by @mem, so that it now has space for - * @n_bytes bytes of memory. It returns the new address of the memory, which may - * have been moved. @mem may be %NULL, in which case it's considered to - * have zero-length. @n_bytes may be 0, in which case %NULL will be returned - * and @mem will be freed unless it is %NULL. - * - * Returns: the new address of the allocated memory - */ - - -/** - * g_realloc_n: - * @mem: (nullable): the memory to reallocate - * @n_blocks: the number of blocks to allocate - * @n_block_bytes: the size of each block in bytes - * - * This function is similar to g_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, - * but care is taken to detect possible overflow during multiplication. - * - * Since: 2.24 - * Returns: the new address of the allocated memory - */ - - -/** - * g_rec_mutex_clear: - * @rec_mutex: an initialized #GRecMutex - * - * Frees the resources allocated to a recursive mutex with - * g_rec_mutex_init(). - * - * This function should not be used with a #GRecMutex that has been - * statically allocated. - * - * Calling g_rec_mutex_clear() on a locked recursive mutex leads - * to undefined behaviour. - * - * Sine: 2.32 - */ - - -/** - * g_rec_mutex_init: - * @rec_mutex: an uninitialized #GRecMutex - * - * Initializes a #GRecMutex so that it can be used. - * - * This function is useful to initialize a recursive mutex - * that has been allocated on the stack, or as part of a larger - * structure. - * - * It is not necessary to initialise a recursive mutex that has been - * statically allocated. - * - * |[<!-- language="C" --> - * typedef struct { - * GRecMutex m; - * ... - * } Blob; - * - * Blob *b; - * - * b = g_new (Blob, 1); - * g_rec_mutex_init (&b->m); - * ]| - * - * Calling g_rec_mutex_init() on an already initialized #GRecMutex - * leads to undefined behaviour. - * - * To undo the effect of g_rec_mutex_init() when a recursive mutex - * is no longer needed, use g_rec_mutex_clear(). - * - * Since: 2.32 - */ - - -/** - * g_rec_mutex_lock: - * @rec_mutex: a #GRecMutex - * - * Locks @rec_mutex. If @rec_mutex is already locked by another - * thread, the current thread will block until @rec_mutex is - * unlocked by the other thread. If @rec_mutex is already locked - * by the current thread, the 'lock count' of @rec_mutex is increased. - * The mutex will only become available again when it is unlocked - * as many times as it has been locked. - * - * Since: 2.32 - */ - - -/** - * g_rec_mutex_trylock: - * @rec_mutex: a #GRecMutex - * - * Tries to lock @rec_mutex. If @rec_mutex is already locked - * by another thread, it immediately returns %FALSE. Otherwise - * it locks @rec_mutex and returns %TRUE. - * - * Returns: %TRUE if @rec_mutex could be locked - * Since: 2.32 - */ - - -/** - * g_rec_mutex_unlock: - * @rec_mutex: a #GRecMutex - * - * Unlocks @rec_mutex. If another thread is blocked in a - * g_rec_mutex_lock() call for @rec_mutex, it will become unblocked - * and can lock @rec_mutex itself. - * - * Calling g_rec_mutex_unlock() on a recursive mutex that is not - * locked by the current thread leads to undefined behaviour. - * - * Since: 2.32 - */ - - -/** - * g_ref_count_compare: - * @rc: the address of a reference count variable - * @val: the value to compare - * - * Compares the current value of @rc with @val. - * - * Returns: %TRUE if the reference count is the same - * as the given value - * Since: 2.58 - */ - - -/** - * g_ref_count_dec: - * @rc: the address of a reference count variable - * - * Decreases the reference count. - * - * If %TRUE is returned, the reference count reached 0. After this point, @rc - * is an undefined state and must be reinitialized with - * g_ref_count_init() to be used again. - * - * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise - * Since: 2.58 - */ - - -/** - * g_ref_count_inc: - * @rc: the address of a reference count variable - * - * Increases the reference count. - * - * Since: 2.58 - */ - - -/** - * g_ref_count_init: - * @rc: the address of a reference count variable - * - * Initializes a reference count variable to 1. - * - * Since: 2.58 - */ - - -/** - * g_ref_string_acquire: - * @str: a reference counted string - * - * Acquires a reference on a string. - * - * Returns: the given string, with its reference count increased - * Since: 2.58 - */ - - -/** - * g_ref_string_length: - * @str: a reference counted string - * - * Retrieves the length of @str. - * - * Returns: the length of the given string, in bytes - * Since: 2.58 - */ - - -/** - * g_ref_string_new: - * @str: (not nullable): a NUL-terminated string - * - * Creates a new reference counted string and copies the contents of @str - * into it. - * - * Returns: (transfer full) (not nullable): the newly created reference counted string - * Since: 2.58 - */ - - -/** - * g_ref_string_new_intern: - * @str: (not nullable): a NUL-terminated string - * - * Creates a new reference counted string and copies the content of @str - * into it. - * - * If you call this function multiple times with the same @str, or with - * the same contents of @str, it will return a new reference, instead of - * creating a new string. - * - * Returns: (transfer full) (not nullable): the newly created reference - * counted string, or a new reference to an existing string - * Since: 2.58 - */ - - -/** - * g_ref_string_new_len: - * @str: (not nullable): a string - * @len: length of @str to use, or -1 if @str is nul-terminated - * - * Creates a new reference counted string and copies the contents of @str - * into it, up to @len bytes. - * - * Since this function does not stop at nul bytes, it is the caller's - * responsibility to ensure that @str has at least @len addressable bytes. - * - * Returns: (transfer full) (not nullable): the newly created reference counted string - * Since: 2.58 - */ - - -/** - * g_ref_string_release: - * @str: a reference counted string - * - * Releases a reference on a string; if it was the last reference, the - * resources allocated by the string are freed as well. - * - * Since: 2.58 - */ - - -/** - * g_regex_check_replacement: - * @replacement: the replacement string - * @has_references: (out) (optional): location to store information about - * references in @replacement or %NULL - * @error: location to store error - * - * Checks whether @replacement is a valid replacement string - * (see g_regex_replace()), i.e. that all escape sequences in - * it are valid. - * - * If @has_references is not %NULL then @replacement is checked - * for pattern references. For instance, replacement text 'foo\n' - * does not contain references and may be evaluated without information - * about actual match, but '\0\1' (whole match followed by first - * subpattern) requires valid #GMatchInfo object. - * - * Returns: whether @replacement is a valid replacement string - * Since: 2.14 - */ - - -/** - * g_regex_escape_nul: - * @string: the string to escape - * @length: the length of @string - * - * Escapes the nul characters in @string to "\x00". It can be used - * to compile a regex with embedded nul characters. - * - * For completeness, @length can be -1 for a nul-terminated string. - * In this case the output string will be of course equal to @string. - * - * Returns: a newly-allocated escaped string - * Since: 2.30 - */ - - -/** - * g_regex_escape_string: - * @string: (array length=length): the string to escape - * @length: the length of @string, in bytes, or -1 if @string is nul-terminated - * - * Escapes the special characters used for regular expressions - * in @string, for instance "a.b*c" becomes "a\.b\*c". This - * function is useful to dynamically generate regular expressions. - * - * @string can contain nul characters that are replaced with "\0", - * in this case remember to specify the correct length of @string - * in @length. - * - * Returns: a newly-allocated escaped string - * Since: 2.14 - */ - - -/** - * g_regex_get_capture_count: - * @regex: a #GRegex - * - * Returns the number of capturing subpatterns in the pattern. - * - * Returns: the number of capturing subpatterns - * Since: 2.14 - */ - - -/** - * g_regex_get_compile_flags: - * @regex: a #GRegex - * - * Returns the compile options that @regex was created with. - * - * Depending on the version of PCRE that is used, this may or may not - * include flags set by option expressions such as `(?i)` found at the - * top-level within the compiled pattern. - * - * Returns: flags from #GRegexCompileFlags - * Since: 2.26 - */ - - -/** - * g_regex_get_has_cr_or_lf: - * @regex: a #GRegex structure - * - * Checks whether the pattern contains explicit CR or LF references. - * - * Returns: %TRUE if the pattern contains explicit CR or LF references - * Since: 2.34 - */ - - -/** - * g_regex_get_match_flags: - * @regex: a #GRegex - * - * Returns the match options that @regex was created with. - * - * Returns: flags from #GRegexMatchFlags - * Since: 2.26 - */ - - -/** - * g_regex_get_max_backref: - * @regex: a #GRegex - * - * Returns the number of the highest back reference - * in the pattern, or 0 if the pattern does not contain - * back references. - * - * Returns: the number of the highest back reference - * Since: 2.14 - */ - - -/** - * g_regex_get_max_lookbehind: - * @regex: a #GRegex structure - * - * Gets the number of characters in the longest lookbehind assertion in the - * pattern. This information is useful when doing multi-segment matching using - * the partial matching facilities. - * - * Returns: the number of characters in the longest lookbehind assertion. - * Since: 2.38 - */ - - -/** - * g_regex_get_pattern: - * @regex: a #GRegex structure - * - * Gets the pattern string associated with @regex, i.e. a copy of - * the string passed to g_regex_new(). - * - * Returns: the pattern of @regex - * Since: 2.14 - */ - - -/** - * g_regex_get_string_number: - * @regex: #GRegex structure - * @name: name of the subexpression - * - * Retrieves the number of the subexpression named @name. - * - * Returns: The number of the subexpression or -1 if @name - * does not exists - * Since: 2.14 - */ - - -/** - * g_regex_match: - * @regex: a #GRegex structure from g_regex_new() - * @string: the string to scan for matches - * @match_options: match options - * @match_info: (out) (optional): pointer to location where to store - * the #GMatchInfo, or %NULL if you do not need it - * - * Scans for a match in @string for the pattern in @regex. - * The @match_options are combined with the match options specified - * when the @regex structure was created, letting you have more - * flexibility in reusing #GRegex structures. - * - * Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. - * - * A #GMatchInfo structure, used to get information on the match, - * is stored in @match_info if not %NULL. Note that if @match_info - * is not %NULL then it is created even if the function returns %FALSE, - * i.e. you must free it regardless if regular expression actually matched. - * - * To retrieve all the non-overlapping matches of the pattern in - * string you can use g_match_info_next(). - * - * |[<!-- language="C" --> - * static void - * print_uppercase_words (const gchar *string) - * { - * // Print all uppercase-only words. - * GRegex *regex; - * GMatchInfo *match_info; - * - * regex = g_regex_new ("[A-Z]+", 0, 0, NULL); - * g_regex_match (regex, string, 0, &match_info); - * while (g_match_info_matches (match_info)) - * { - * gchar *word = g_match_info_fetch (match_info, 0); - * g_print ("Found: %s\n", word); - * g_free (word); - * g_match_info_next (match_info, NULL); - * } - * g_match_info_free (match_info); - * g_regex_unref (regex); - * } - * ]| - * - * @string is not copied and is used in #GMatchInfo internally. If - * you use any #GMatchInfo method (except g_match_info_free()) after - * freeing or modifying @string then the behaviour is undefined. - * - * Returns: %TRUE is the string matched, %FALSE otherwise - * Since: 2.14 - */ - - -/** - * g_regex_match_all: - * @regex: a #GRegex structure from g_regex_new() - * @string: the string to scan for matches - * @match_options: match options - * @match_info: (out) (optional): pointer to location where to store - * the #GMatchInfo, or %NULL if you do not need it - * - * Using the standard algorithm for regular expression matching only - * the longest match in the string is retrieved. This function uses - * a different algorithm so it can retrieve all the possible matches. - * For more documentation see g_regex_match_all_full(). - * - * A #GMatchInfo structure, used to get information on the match, is - * stored in @match_info if not %NULL. Note that if @match_info is - * not %NULL then it is created even if the function returns %FALSE, - * i.e. you must free it regardless if regular expression actually - * matched. - * - * @string is not copied and is used in #GMatchInfo internally. If - * you use any #GMatchInfo method (except g_match_info_free()) after - * freeing or modifying @string then the behaviour is undefined. - * - * Returns: %TRUE is the string matched, %FALSE otherwise - * Since: 2.14 - */ - - -/** - * g_regex_match_all_full: - * @regex: a #GRegex structure from g_regex_new() - * @string: (array length=string_len): the string to scan for matches - * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated - * @start_position: starting index of the string to match, in bytes - * @match_options: match options - * @match_info: (out) (optional): pointer to location where to store - * the #GMatchInfo, or %NULL if you do not need it - * @error: location to store the error occurring, or %NULL to ignore errors - * - * Using the standard algorithm for regular expression matching only - * the longest match in the @string is retrieved, it is not possible - * to obtain all the available matches. For instance matching - * "<a> <b> <c>" against the pattern "<.*>" - * you get "<a> <b> <c>". - * - * This function uses a different algorithm (called DFA, i.e. deterministic - * finite automaton), so it can retrieve all the possible matches, all - * starting at the same point in the string. For instance matching - * "<a> <b> <c>" against the pattern "<.*>;" - * you would obtain three matches: "<a> <b> <c>", - * "<a> <b>" and "<a>". - * - * The number of matched strings is retrieved using - * g_match_info_get_match_count(). To obtain the matched strings and - * their position you can use, respectively, g_match_info_fetch() and - * g_match_info_fetch_pos(). Note that the strings are returned in - * reverse order of length; that is, the longest matching string is - * given first. - * - * Note that the DFA algorithm is slower than the standard one and it - * is not able to capture substrings, so backreferences do not work. - * - * Setting @start_position 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, such as "\b". - * - * Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. - * - * A #GMatchInfo structure, used to get information on the match, is - * stored in @match_info if not %NULL. Note that if @match_info is - * not %NULL then it is created even if the function returns %FALSE, - * i.e. you must free it regardless if regular expression actually - * matched. - * - * @string is not copied and is used in #GMatchInfo internally. If - * you use any #GMatchInfo method (except g_match_info_free()) after - * freeing or modifying @string then the behaviour is undefined. - * - * Returns: %TRUE is the string matched, %FALSE otherwise - * Since: 2.14 - */ - - -/** - * g_regex_match_full: - * @regex: a #GRegex structure from g_regex_new() - * @string: (array length=string_len): the string to scan for matches - * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated - * @start_position: starting index of the string to match, in bytes - * @match_options: match options - * @match_info: (out) (optional): pointer to location where to store - * the #GMatchInfo, or %NULL if you do not need it - * @error: location to store the error occurring, or %NULL to ignore errors - * - * Scans for a match in @string for the pattern in @regex. - * The @match_options are combined with the match options specified - * when the @regex structure was created, letting you have more - * flexibility in reusing #GRegex structures. - * - * Setting @start_position 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, such as "\b". - * - * Unless %G_REGEX_RAW is specified in the options, @string must be valid UTF-8. - * - * A #GMatchInfo structure, used to get information on the match, is - * stored in @match_info if not %NULL. Note that if @match_info is - * not %NULL then it is created even if the function returns %FALSE, - * i.e. you must free it regardless if regular expression actually - * matched. - * - * @string is not copied and is used in #GMatchInfo internally. If - * you use any #GMatchInfo method (except g_match_info_free()) after - * freeing or modifying @string then the behaviour is undefined. - * - * To retrieve all the non-overlapping matches of the pattern in - * string you can use g_match_info_next(). - * - * |[<!-- language="C" --> - * static void - * print_uppercase_words (const gchar *string) - * { - * // Print all uppercase-only words. - * GRegex *regex; - * GMatchInfo *match_info; - * GError *error = NULL; - * - * regex = g_regex_new ("[A-Z]+", 0, 0, NULL); - * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error); - * while (g_match_info_matches (match_info)) - * { - * gchar *word = g_match_info_fetch (match_info, 0); - * g_print ("Found: %s\n", word); - * g_free (word); - * g_match_info_next (match_info, &error); - * } - * g_match_info_free (match_info); - * g_regex_unref (regex); - * if (error != NULL) - * { - * g_printerr ("Error while matching: %s\n", error->message); - * g_error_free (error); - * } - * } - * ]| - * - * Returns: %TRUE is the string matched, %FALSE otherwise - * Since: 2.14 - */ - - -/** - * g_regex_match_simple: - * @pattern: the regular expression - * @string: the string to scan for matches - * @compile_options: compile options for the regular expression, or 0 - * @match_options: match options, or 0 - * - * Scans for a match in @string for @pattern. - * - * This function is equivalent to g_regex_match() but it does not - * require to compile the pattern with g_regex_new(), avoiding some - * lines of code when you need just to do a match without extracting - * substrings, capture counts, and so on. - * - * If this function is to be called on the same @pattern more than - * once, it's more efficient to compile the pattern once with - * g_regex_new() and then use g_regex_match(). - * - * Returns: %TRUE if the string matched, %FALSE otherwise - * Since: 2.14 - */ - - -/** - * g_regex_new: - * @pattern: the regular expression - * @compile_options: compile options for the regular expression, or 0 - * @match_options: match options for the regular expression, or 0 - * @error: return location for a #GError - * - * Compiles the regular expression to an internal form, and does - * the initial setup of the #GRegex structure. - * - * Returns: (nullable): a #GRegex structure or %NULL if an error occurred. Call - * g_regex_unref() when you are done with it - * Since: 2.14 - */ - - -/** - * g_regex_ref: - * @regex: a #GRegex - * - * Increases reference count of @regex by 1. - * - * Returns: @regex - * Since: 2.14 - */ - - -/** - * g_regex_replace: - * @regex: a #GRegex structure - * @string: (array length=string_len): the string to perform matches against - * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated - * @start_position: starting index of the string to match, in bytes - * @replacement: text to replace each match with - * @match_options: options for the match - * @error: location to store the error occurring, or %NULL to ignore errors - * - * Replaces all occurrences of the pattern in @regex with the - * replacement text. Backreferences of the form '\number' or - * '\g<number>' in the replacement text are interpolated by the - * number-th captured subexpression of the match, '\g<name>' refers - * to the captured subexpression with the given name. '\0' refers - * to the complete match, but '\0' followed by a number is the octal - * representation of a character. To include a literal '\' in the - * replacement, write '\\\\'. - * - * There are also escapes that changes the case of the following text: - * - * - \l: Convert to lower case the next character - * - \u: Convert to upper case the next character - * - \L: Convert to lower case till \E - * - \U: Convert to upper case till \E - * - \E: End case modification - * - * If you do not need to use backreferences use g_regex_replace_literal(). - * - * The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was - * passed to g_regex_new(). If you want to use not UTF-8 encoded strings - * you can use g_regex_replace_literal(). - * - * Setting @start_position 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, such as "\b". - * - * Returns: a newly allocated string containing the replacements - * Since: 2.14 - */ - - -/** - * g_regex_replace_eval: - * @regex: a #GRegex structure from g_regex_new() - * @string: (array length=string_len): string to perform matches against - * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated - * @start_position: starting index of the string to match, in bytes - * @match_options: options for the match - * @eval: a function to call for each match - * @user_data: user data to pass to the function - * @error: location to store the error occurring, or %NULL to ignore errors - * - * Replaces occurrences of the pattern in regex with the output of - * @eval for that occurrence. - * - * Setting @start_position 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, such as "\b". - * - * The following example uses g_regex_replace_eval() to replace multiple - * strings at once: - * |[<!-- language="C" --> - * static gboolean - * eval_cb (const GMatchInfo *info, - * GString *res, - * gpointer data) - * { - * gchar *match; - * gchar *r; - * - * match = g_match_info_fetch (info, 0); - * r = g_hash_table_lookup ((GHashTable *)data, match); - * g_string_append (res, r); - * g_free (match); - * - * return FALSE; - * } - * - * ... - * - * GRegex *reg; - * GHashTable *h; - * gchar *res; - * - * h = g_hash_table_new (g_str_hash, g_str_equal); - * - * g_hash_table_insert (h, "1", "ONE"); - * g_hash_table_insert (h, "2", "TWO"); - * g_hash_table_insert (h, "3", "THREE"); - * g_hash_table_insert (h, "4", "FOUR"); - * - * reg = g_regex_new ("1|2|3|4", 0, 0, NULL); - * res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL); - * g_hash_table_destroy (h); - * - * ... - * ]| - * - * Returns: a newly allocated string containing the replacements - * Since: 2.14 - */ - - -/** - * g_regex_replace_literal: - * @regex: a #GRegex structure - * @string: (array length=string_len): the string to perform matches against - * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated - * @start_position: starting index of the string to match, in bytes - * @replacement: text to replace each match with - * @match_options: options for the match - * @error: location to store the error occurring, or %NULL to ignore errors - * - * Replaces all occurrences of the pattern in @regex with the - * replacement text. @replacement is replaced literally, to - * include backreferences use g_regex_replace(). - * - * Setting @start_position 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, such as "\b". - * - * Returns: a newly allocated string containing the replacements - * Since: 2.14 - */ - - -/** - * g_regex_split: - * @regex: a #GRegex structure - * @string: the string to split with the pattern - * @match_options: match time option flags - * - * Breaks the string on the pattern, and returns an array of the tokens. - * If the pattern contains capturing parentheses, then the text for each - * of the substrings will also be returned. If the pattern does not match - * anywhere in the string, then the whole string is returned as the first - * token. - * - * As a special case, the result of splitting the empty string "" is an - * empty vector, not a vector containing a single string. The reason for - * this special case is that being able to represent an empty vector is - * typically more useful than consistent handling of empty elements. If - * you do need to represent empty elements, you'll need to check for the - * empty string before calling this function. - * - * A pattern that can match empty strings splits @string into separate - * characters wherever it matches the empty string between characters. - * For example splitting "ab c" using as a separator "\s*", you will get - * "a", "b" and "c". - * - * Returns: (transfer full): a %NULL-terminated gchar ** array. Free - * it using g_strfreev() - * Since: 2.14 - */ - - -/** - * g_regex_split_full: - * @regex: a #GRegex structure - * @string: (array length=string_len): the string to split with the pattern - * @string_len: the length of @string, in bytes, or -1 if @string is nul-terminated - * @start_position: starting index of the string to match, in bytes - * @match_options: match time option flags - * @max_tokens: the maximum number of tokens to split @string into. - * If this is less than 1, the string is split completely - * @error: return location for a #GError - * - * Breaks the string on the pattern, and returns an array of the tokens. - * If the pattern contains capturing parentheses, then the text for each - * of the substrings will also be returned. If the pattern does not match - * anywhere in the string, then the whole string is returned as the first - * token. - * - * As a special case, the result of splitting the empty string "" is an - * empty vector, not a vector containing a single string. The reason for - * this special case is that being able to represent an empty vector is - * typically more useful than consistent handling of empty elements. If - * you do need to represent empty elements, you'll need to check for the - * empty string before calling this function. - * - * A pattern that can match empty strings splits @string into separate - * characters wherever it matches the empty string between characters. - * For example splitting "ab c" using as a separator "\s*", you will get - * "a", "b" and "c". - * - * Setting @start_position 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, such as "\b". - * - * Returns: (transfer full): a %NULL-terminated gchar ** array. Free - * it using g_strfreev() - * Since: 2.14 - */ - - -/** - * g_regex_split_simple: - * @pattern: the regular expression - * @string: the string to scan for matches - * @compile_options: compile options for the regular expression, or 0 - * @match_options: match options, or 0 - * - * Breaks the string on the pattern, and returns an array of - * the tokens. If the pattern contains capturing parentheses, - * then the text for each of the substrings will also be returned. - * If the pattern does not match anywhere in the string, then the - * whole string is returned as the first token. - * - * This function is equivalent to g_regex_split() but it does - * not require to compile the pattern with g_regex_new(), avoiding - * some lines of code when you need just to do a split without - * extracting substrings, capture counts, and so on. - * - * If this function is to be called on the same @pattern more than - * once, it's more efficient to compile the pattern once with - * g_regex_new() and then use g_regex_split(). - * - * As a special case, the result of splitting the empty string "" - * is an empty vector, not a vector containing a single string. - * The reason for this special case is that being able to represent - * an empty vector is typically more useful than consistent handling - * of empty elements. If you do need to represent empty elements, - * you'll need to check for the empty string before calling this - * function. - * - * A pattern that can match empty strings splits @string into - * separate characters wherever it matches the empty string between - * characters. For example splitting "ab c" using as a separator - * "\s*", you will get "a", "b" and "c". - * - * Returns: (transfer full): a %NULL-terminated array of strings. Free - * it using g_strfreev() - * Since: 2.14 - */ - - -/** - * g_regex_unref: - * @regex: a #GRegex - * - * Decreases reference count of @regex by 1. When reference count drops - * to zero, it frees all the memory associated with the regex structure. - * - * Since: 2.14 - */ - - -/** - * g_reload_user_special_dirs_cache: - * - * Resets the cache used for g_get_user_special_dir(), so - * that the latest on-disk version is used. Call this only - * if you just changed the data on disk yourself. - * - * Due to thread safety issues this may cause leaking of strings - * that were previously returned from g_get_user_special_dir() - * that can't be freed. We ensure to only leak the data for - * the directories that actually changed value though. - * - * Since: 2.22 - */ - - -/** - * g_remove: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * - * A wrapper for the POSIX remove() function. The remove() function - * deletes a name from the filesystem. - * - * See your C library manual for more details about how remove() works - * on your system. On Unix, remove() removes also directories, as it - * calls unlink() for files and rmdir() for directories. On Windows, - * although remove() in the C library only works for files, this - * function tries first remove() and then if that fails rmdir(), and - * thus works for both files and directories. Note however, that on - * Windows, it is in general not possible to remove a file that is - * open to some process, or mapped into memory. - * - * If this function fails on Windows you can't infer too much from the - * errno value. rmdir() is tried regardless of what caused remove() to - * fail. Any errno value set by remove() will be overwritten by that - * set by rmdir(). - * - * Returns: 0 if the file was successfully removed, -1 if an error - * occurred - * Since: 2.6 - */ - - -/** - * g_rename: - * @oldfilename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * @newfilename: (type filename): a pathname in the GLib file name encoding - * - * A wrapper for the POSIX rename() function. The rename() function - * renames a file, moving it between directories if required. - * - * See your C library manual for more details about how rename() works - * on your system. It is not possible in general on Windows to rename - * a file that is open to some process. - * - * Returns: 0 if the renaming succeeded, -1 if an error occurred - * Since: 2.6 - */ - - -/** - * g_return_if_fail_warning: (skip) - * @log_domain: (nullable): log domain - * @pretty_function: function containing the assertion - * @expression: (nullable): expression which failed - * - * Internal function used to print messages from the public g_return_if_fail() - * and g_return_val_if_fail() macros. - */ - - -/** - * g_rmdir: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * - * A wrapper for the POSIX rmdir() function. The rmdir() function - * deletes a directory from the filesystem. - * - * See your C library manual for more details about how rmdir() works - * on your system. - * - * Returns: 0 if the directory was successfully removed, -1 if an error - * occurred - * Since: 2.6 - */ - - -/** - * g_rw_lock_clear: - * @rw_lock: an initialized #GRWLock - * - * Frees the resources allocated to a lock with g_rw_lock_init(). - * - * This function should not be used with a #GRWLock that has been - * statically allocated. - * - * Calling g_rw_lock_clear() when any thread holds the lock - * leads to undefined behaviour. - * - * Sine: 2.32 - */ - - -/** - * g_rw_lock_init: - * @rw_lock: an uninitialized #GRWLock - * - * Initializes a #GRWLock so that it can be used. - * - * This function is useful to initialize a lock that has been - * allocated on the stack, or as part of a larger structure. It is not - * necessary to initialise a reader-writer lock that has been statically - * allocated. - * - * |[<!-- language="C" --> - * typedef struct { - * GRWLock l; - * ... - * } Blob; - * - * Blob *b; - * - * b = g_new (Blob, 1); - * g_rw_lock_init (&b->l); - * ]| - * - * To undo the effect of g_rw_lock_init() when a lock is no longer - * needed, use g_rw_lock_clear(). - * - * Calling g_rw_lock_init() on an already initialized #GRWLock leads - * to undefined behaviour. - * - * Since: 2.32 - */ - - -/** - * g_rw_lock_reader_lock: - * @rw_lock: a #GRWLock - * - * Obtain a read lock on @rw_lock. If another thread currently holds - * the write lock on @rw_lock, the current thread will block until the - * write lock was (held and) released. If another thread does not hold - * the write lock, but is waiting for it, it is implementation defined - * whether the reader or writer will block. Read locks can be taken - * recursively. - * - * Calling g_rw_lock_reader_lock() while the current thread already - * owns a write lock leads to undefined behaviour. Read locks however - * can be taken recursively, in which case you need to make sure to - * call g_rw_lock_reader_unlock() the same amount of times. - * - * It is implementation-defined how many read locks are allowed to be - * held on the same lock simultaneously. If the limit is hit, - * or if a deadlock is detected, a critical warning will be emitted. - * - * Since: 2.32 - */ - - -/** - * g_rw_lock_reader_trylock: - * @rw_lock: a #GRWLock - * - * Tries to obtain a read lock on @rw_lock and returns %TRUE if - * the read lock was successfully obtained. Otherwise it - * returns %FALSE. - * - * Returns: %TRUE if @rw_lock could be locked - * Since: 2.32 - */ - - -/** - * g_rw_lock_reader_unlock: - * @rw_lock: a #GRWLock - * - * Release a read lock on @rw_lock. - * - * Calling g_rw_lock_reader_unlock() on a lock that is not held - * by the current thread leads to undefined behaviour. - * - * Since: 2.32 - */ - - -/** - * g_rw_lock_writer_lock: - * @rw_lock: a #GRWLock - * - * Obtain a write lock on @rw_lock. If another thread currently holds - * a read or write lock on @rw_lock, the current thread will block - * until all other threads have dropped their locks on @rw_lock. - * - * Calling g_rw_lock_writer_lock() while the current thread already - * owns a read or write lock on @rw_lock leads to undefined behaviour. - * - * Since: 2.32 - */ - - -/** - * g_rw_lock_writer_trylock: - * @rw_lock: a #GRWLock - * - * Tries to obtain a write lock on @rw_lock. If another thread - * currently holds a read or write lock on @rw_lock, it immediately - * returns %FALSE. - * Otherwise it locks @rw_lock and returns %TRUE. - * - * Returns: %TRUE if @rw_lock could be locked - * Since: 2.32 - */ - - -/** - * g_rw_lock_writer_unlock: - * @rw_lock: a #GRWLock - * - * Release a write lock on @rw_lock. - * - * Calling g_rw_lock_writer_unlock() on a lock that is not held - * by the current thread leads to undefined behaviour. - * - * Since: 2.32 - */ - - -/** - * g_scanner_add_symbol: - * @scanner: a #GScanner - * @symbol: the symbol to add - * @value: the value of the symbol - * - * Adds a symbol to the default scope. - * - * Deprecated: 2.2: Use g_scanner_scope_add_symbol() instead. - */ - - -/** - * g_scanner_cur_line: - * @scanner: a #GScanner - * - * Returns the current line in the input stream (counting - * from 1). This is the line of the last token parsed via - * g_scanner_get_next_token(). - * - * Returns: the current line - */ - - -/** - * g_scanner_cur_position: - * @scanner: a #GScanner - * - * Returns the current position in the current line (counting - * from 0). This is the position of the last token parsed via - * g_scanner_get_next_token(). - * - * Returns: the current position on the line - */ - - -/** - * g_scanner_cur_token: - * @scanner: a #GScanner - * - * Gets the current token type. This is simply the @token - * field in the #GScanner structure. - * - * Returns: the current token type - */ - - -/** - * g_scanner_cur_value: - * @scanner: a #GScanner - * - * Gets the current token value. This is simply the @value - * field in the #GScanner structure. - * - * Returns: the current token value - */ - - -/** - * g_scanner_destroy: - * @scanner: a #GScanner - * - * Frees all memory used by the #GScanner. - */ - - -/** - * g_scanner_eof: - * @scanner: a #GScanner - * - * Returns %TRUE if the scanner has reached the end of - * the file or text buffer. - * - * Returns: %TRUE if the scanner has reached the end of - * the file or text buffer - */ - - -/** - * g_scanner_error: - * @scanner: a #GScanner - * @format: the message format. See the printf() documentation - * @...: the parameters to insert into the format string - * - * Outputs an error message, via the #GScanner message handler. - */ - - -/** - * g_scanner_foreach_symbol: - * @scanner: a #GScanner - * @func: the function to call with each symbol - * @data: data to pass to the function - * - * Calls a function for each symbol in the default scope. - * - * Deprecated: 2.2: Use g_scanner_scope_foreach_symbol() instead. - */ - - -/** - * g_scanner_freeze_symbol_table: - * @scanner: a #GScanner - * - * There is no reason to use this macro, since it does nothing. - * - * Deprecated: 2.2: This macro does nothing. - */ - - -/** - * g_scanner_get_next_token: - * @scanner: a #GScanner - * - * Parses the next token just like g_scanner_peek_next_token() - * and also removes it from the input stream. The token data is - * placed in the @token, @value, @line, and @position fields of - * the #GScanner structure. - * - * Returns: the type of the token - */ - - -/** - * g_scanner_input_file: - * @scanner: a #GScanner - * @input_fd: a file descriptor - * - * Prepares to scan a file. - */ - - -/** - * g_scanner_input_text: - * @scanner: a #GScanner - * @text: the text buffer to scan - * @text_len: the length of the text buffer - * - * Prepares to scan a text buffer. - */ - - -/** - * g_scanner_lookup_symbol: - * @scanner: a #GScanner - * @symbol: the symbol to look up - * - * Looks up a symbol in the current scope and return its value. - * If the symbol is not bound in the current scope, %NULL is - * returned. - * - * Returns: the value of @symbol in the current scope, or %NULL - * if @symbol is not bound in the current scope - */ - - -/** - * g_scanner_new: - * @config_templ: the initial scanner settings - * - * Creates a new #GScanner. - * - * The @config_templ structure specifies the initial settings - * of the scanner, which are copied into the #GScanner - * @config field. If you pass %NULL then the default settings - * are used. - * - * Returns: the new #GScanner - */ - - -/** - * g_scanner_peek_next_token: - * @scanner: a #GScanner - * - * Parses the next token, without removing it from the input stream. - * The token data is placed in the @next_token, @next_value, @next_line, - * and @next_position fields of the #GScanner structure. - * - * Note that, while the token is not removed from the input stream - * (i.e. the next call to g_scanner_get_next_token() will return the - * same token), it will not be reevaluated. This can lead to surprising - * results when changing scope or the scanner configuration after peeking - * the next token. Getting the next token after switching the scope or - * configuration will return whatever was peeked before, regardless of - * any symbols that may have been added or removed in the new scope. - * - * Returns: the type of the token - */ - - -/** - * g_scanner_remove_symbol: - * @scanner: a #GScanner - * @symbol: the symbol to remove - * - * Removes a symbol from the default scope. - * - * Deprecated: 2.2: Use g_scanner_scope_remove_symbol() instead. - */ - - -/** - * g_scanner_scope_add_symbol: - * @scanner: a #GScanner - * @scope_id: the scope id - * @symbol: the symbol to add - * @value: the value of the symbol - * - * Adds a symbol to the given scope. - */ - - -/** - * g_scanner_scope_foreach_symbol: - * @scanner: a #GScanner - * @scope_id: the scope id - * @func: the function to call for each symbol/value pair - * @user_data: user data to pass to the function - * - * Calls the given function for each of the symbol/value pairs - * in the given scope of the #GScanner. The function is passed - * the symbol and value of each pair, and the given @user_data - * parameter. - */ - - -/** - * g_scanner_scope_lookup_symbol: - * @scanner: a #GScanner - * @scope_id: the scope id - * @symbol: the symbol to look up - * - * Looks up a symbol in a scope and return its value. If the - * symbol is not bound in the scope, %NULL is returned. - * - * Returns: the value of @symbol in the given scope, or %NULL - * if @symbol is not bound in the given scope. - */ - - -/** - * g_scanner_scope_remove_symbol: - * @scanner: a #GScanner - * @scope_id: the scope id - * @symbol: the symbol to remove - * - * Removes a symbol from a scope. - */ - - -/** - * g_scanner_set_scope: - * @scanner: a #GScanner - * @scope_id: the new scope id - * - * Sets the current scope. - * - * Returns: the old scope id - */ - - -/** - * g_scanner_sync_file_offset: - * @scanner: a #GScanner - * - * Rewinds the filedescriptor to the current buffer position - * and blows the file read ahead buffer. This is useful for - * third party uses of the scanners filedescriptor, which hooks - * onto the current scanning position. - */ - - -/** - * g_scanner_thaw_symbol_table: - * @scanner: a #GScanner - * - * There is no reason to use this macro, since it does nothing. - * - * Deprecated: 2.2: This macro does nothing. - */ - - -/** - * g_scanner_unexp_token: - * @scanner: a #GScanner - * @expected_token: the expected token - * @identifier_spec: a string describing how the scanner's user - * refers to identifiers (%NULL defaults to "identifier"). - * This is used if @expected_token is %G_TOKEN_IDENTIFIER or - * %G_TOKEN_IDENTIFIER_NULL. - * @symbol_spec: a string describing how the scanner's user refers - * to symbols (%NULL defaults to "symbol"). This is used if - * @expected_token is %G_TOKEN_SYMBOL or any token value greater - * than %G_TOKEN_LAST. - * @symbol_name: the name of the symbol, if the scanner's current - * token is a symbol. - * @message: a message string to output at the end of the - * warning/error, or %NULL. - * @is_error: if %TRUE it is output as an error. If %FALSE it is - * output as a warning. - * - * Outputs a message through the scanner's msg_handler, - * resulting from an unexpected token in the input stream. - * Note that you should not call g_scanner_peek_next_token() - * followed by g_scanner_unexp_token() without an intermediate - * call to g_scanner_get_next_token(), as g_scanner_unexp_token() - * evaluates the scanner's current token (not the peeked token) - * to construct part of the message. - */ - - -/** - * g_scanner_warn: - * @scanner: a #GScanner - * @format: the message format. See the printf() documentation - * @...: the parameters to insert into the format string - * - * Outputs a warning message, via the #GScanner message handler. - */ - - -/** - * g_sequence_append: - * @seq: a #GSequence - * @data: the data for the new item - * - * Adds a new item to the end of @seq. - * - * Returns: (transfer none): an iterator pointing to the new item - * Since: 2.14 - */ - - -/** - * g_sequence_foreach: - * @seq: a #GSequence - * @func: the function to call for each item in @seq - * @user_data: user data passed to @func - * - * Calls @func for each item in the sequence passing @user_data - * to the function. @func must not modify the sequence itself. - * - * Since: 2.14 - */ - - -/** - * g_sequence_foreach_range: - * @begin: a #GSequenceIter - * @end: a #GSequenceIter - * @func: a #GFunc - * @user_data: user data passed to @func - * - * Calls @func for each item in the range (@begin, @end) passing - * @user_data to the function. @func must not modify the sequence - * itself. - * - * Since: 2.14 - */ - - -/** - * g_sequence_free: - * @seq: a #GSequence - * - * Frees the memory allocated for @seq. If @seq has a data destroy - * function associated with it, that function is called on all items - * in @seq. - * - * Since: 2.14 - */ - - -/** - * g_sequence_get: - * @iter: a #GSequenceIter - * - * Returns the data that @iter points to. - * - * Returns: (transfer none): the data that @iter points to - * Since: 2.14 - */ - - -/** - * g_sequence_get_begin_iter: - * @seq: a #GSequence - * - * Returns the begin iterator for @seq. - * - * Returns: (transfer none): the begin iterator for @seq. - * Since: 2.14 - */ - - -/** - * g_sequence_get_end_iter: - * @seq: a #GSequence - * - * Returns the end iterator for @seg - * - * Returns: (transfer none): the end iterator for @seq - * Since: 2.14 - */ - - -/** - * g_sequence_get_iter_at_pos: - * @seq: a #GSequence - * @pos: a position in @seq, or -1 for the end - * - * Returns the iterator at position @pos. If @pos is negative or larger - * than the number of items in @seq, the end iterator is returned. - * - * Returns: (transfer none): The #GSequenceIter at position @pos - * Since: 2.14 - */ - - -/** - * g_sequence_get_length: - * @seq: a #GSequence - * - * Returns the positive length (>= 0) of @seq. Note that this method is - * O(h) where `h' is the height of the tree. It is thus more efficient - * to use g_sequence_is_empty() when comparing the length to zero. - * - * Returns: the length of @seq - * Since: 2.14 - */ - - -/** - * g_sequence_insert_before: - * @iter: a #GSequenceIter - * @data: the data for the new item - * - * Inserts a new item just before the item pointed to by @iter. - * - * Returns: (transfer none): an iterator pointing to the new item - * Since: 2.14 - */ - - -/** - * g_sequence_insert_sorted: - * @seq: a #GSequence - * @data: the data to insert - * @cmp_func: the function used to compare items in the sequence - * @cmp_data: user data passed to @cmp_func. - * - * Inserts @data into @seq using @cmp_func to determine the new - * position. The sequence must already be sorted according to @cmp_func; - * otherwise the new position of @data is undefined. - * - * @cmp_func is called with two items of the @seq, and @cmp_data. - * It should return 0 if the items are equal, a negative value - * if the first item comes before the second, and a positive value - * if the second item comes before the first. - * - * Note that when adding a large amount of data to a #GSequence, - * it is more efficient to do unsorted insertions and then call - * g_sequence_sort() or g_sequence_sort_iter(). - * - * Returns: (transfer none): a #GSequenceIter pointing to the new item. - * Since: 2.14 - */ - - -/** - * g_sequence_insert_sorted_iter: - * @seq: a #GSequence - * @data: data for the new item - * @iter_cmp: the function used to compare iterators in the sequence - * @cmp_data: user data passed to @iter_cmp - * - * Like g_sequence_insert_sorted(), but uses - * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as - * the compare function. - * - * @iter_cmp is called with two iterators pointing into @seq. - * It should return 0 if the iterators are equal, a negative - * value if the first iterator comes before the second, and a - * positive value if the second iterator comes before the first. - * - * Note that when adding a large amount of data to a #GSequence, - * it is more efficient to do unsorted insertions and then call - * g_sequence_sort() or g_sequence_sort_iter(). - * - * Returns: (transfer none): a #GSequenceIter pointing to the new item - * Since: 2.14 - */ - - -/** - * g_sequence_is_empty: - * @seq: a #GSequence - * - * Returns %TRUE if the sequence contains zero items. - * - * This function is functionally identical to checking the result of - * g_sequence_get_length() being equal to zero. However this function is - * implemented in O(1) running time. - * - * Returns: %TRUE if the sequence is empty, otherwise %FALSE. - * Since: 2.48 - */ - - -/** - * g_sequence_iter_compare: - * @a: a #GSequenceIter - * @b: a #GSequenceIter - * - * Returns a negative number if @a comes before @b, 0 if they are equal, - * and a positive number if @a comes after @b. - * - * The @a and @b iterators must point into the same sequence. - * - * Returns: a negative number if @a comes before @b, 0 if they are - * equal, and a positive number if @a comes after @b - * Since: 2.14 - */ - - -/** - * g_sequence_iter_get_position: - * @iter: a #GSequenceIter - * - * Returns the position of @iter - * - * Returns: the position of @iter - * Since: 2.14 - */ - - -/** - * g_sequence_iter_get_sequence: - * @iter: a #GSequenceIter - * - * Returns the #GSequence that @iter points into. - * - * Returns: (transfer none): the #GSequence that @iter points into - * Since: 2.14 - */ - - -/** - * g_sequence_iter_is_begin: - * @iter: a #GSequenceIter - * - * Returns whether @iter is the begin iterator - * - * Returns: whether @iter is the begin iterator - * Since: 2.14 - */ - - -/** - * g_sequence_iter_is_end: - * @iter: a #GSequenceIter - * - * Returns whether @iter is the end iterator - * - * Returns: Whether @iter is the end iterator - * Since: 2.14 - */ - - -/** - * g_sequence_iter_move: - * @iter: a #GSequenceIter - * @delta: A positive or negative number indicating how many positions away - * from @iter the returned #GSequenceIter will be - * - * Returns the #GSequenceIter which is @delta positions away from @iter. - * If @iter is closer than -@delta positions to the beginning of the sequence, - * the begin iterator is returned. If @iter is closer than @delta positions - * to the end of the sequence, the end iterator is returned. - * - * Returns: (transfer none): a #GSequenceIter which is @delta positions away from @iter - * Since: 2.14 - */ - - -/** - * g_sequence_iter_next: - * @iter: a #GSequenceIter - * - * Returns an iterator pointing to the next position after @iter. - * If @iter is the end iterator, the end iterator is returned. - * - * Returns: (transfer none): a #GSequenceIter pointing to the next position after @iter - * Since: 2.14 - */ - - -/** - * g_sequence_iter_prev: - * @iter: a #GSequenceIter - * - * Returns an iterator pointing to the previous position before @iter. - * If @iter is the begin iterator, the begin iterator is returned. - * - * Returns: (transfer none): a #GSequenceIter pointing to the previous position - * before @iter - * Since: 2.14 - */ - - -/** - * g_sequence_lookup: - * @seq: a #GSequence - * @data: data to look up - * @cmp_func: the function used to compare items in the sequence - * @cmp_data: user data passed to @cmp_func - * - * Returns an iterator pointing to the position of the first item found - * equal to @data according to @cmp_func and @cmp_data. If more than one - * item is equal, it is not guaranteed that it is the first which is - * returned. In that case, you can use g_sequence_iter_next() and - * g_sequence_iter_prev() to get others. - * - * @cmp_func is called with two items of the @seq, and @cmp_data. - * It should return 0 if the items are equal, a negative value if - * the first item comes before the second, and a positive value if - * the second item comes before the first. - * - * This function will fail if the data contained in the sequence is - * unsorted. - * - * Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of the - * first item found equal to @data according to @cmp_func and - * @cmp_data, or %NULL if no such item exists - * Since: 2.28 - */ - - -/** - * g_sequence_lookup_iter: - * @seq: a #GSequence - * @data: data to look up - * @iter_cmp: the function used to compare iterators in the sequence - * @cmp_data: user data passed to @iter_cmp - * - * Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc - * instead of a #GCompareDataFunc as the compare function. - * - * @iter_cmp is called with two iterators pointing into @seq. - * It should return 0 if the iterators are equal, a negative value - * if the first iterator comes before the second, and a positive - * value if the second iterator comes before the first. - * - * This function will fail if the data contained in the sequence is - * unsorted. - * - * Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of - * the first item found equal to @data according to @iter_cmp - * and @cmp_data, or %NULL if no such item exists - * Since: 2.28 - */ - - -/** - * g_sequence_move: - * @src: a #GSequenceIter pointing to the item to move - * @dest: a #GSequenceIter pointing to the position to which - * the item is moved - * - * Moves the item pointed to by @src to the position indicated by @dest. - * After calling this function @dest will point to the position immediately - * after @src. It is allowed for @src and @dest to point into different - * sequences. - * - * Since: 2.14 - */ - - -/** - * g_sequence_move_range: - * @dest: a #GSequenceIter - * @begin: a #GSequenceIter - * @end: a #GSequenceIter - * - * Inserts the (@begin, @end) range at the destination pointed to by @dest. - * The @begin and @end iters must point into the same sequence. It is - * allowed for @dest to point to a different sequence than the one pointed - * into by @begin and @end. - * - * If @dest is %NULL, the range indicated by @begin and @end is - * removed from the sequence. If @dest points to a place within - * the (@begin, @end) range, the range does not move. - * - * Since: 2.14 - */ - - -/** - * g_sequence_new: - * @data_destroy: (nullable): a #GDestroyNotify function, or %NULL - * - * Creates a new GSequence. The @data_destroy function, if non-%NULL will - * be called on all items when the sequence is destroyed and on items that - * are removed from the sequence. - * - * Returns: (transfer full): a new #GSequence - * Since: 2.14 - */ - - -/** - * g_sequence_prepend: - * @seq: a #GSequence - * @data: the data for the new item - * - * Adds a new item to the front of @seq - * - * Returns: (transfer none): an iterator pointing to the new item - * Since: 2.14 - */ - - -/** - * g_sequence_range_get_midpoint: - * @begin: a #GSequenceIter - * @end: a #GSequenceIter - * - * Finds an iterator somewhere in the range (@begin, @end). This - * iterator will be close to the middle of the range, but is not - * guaranteed to be exactly in the middle. - * - * The @begin and @end iterators must both point to the same sequence - * and @begin must come before or be equal to @end in the sequence. - * - * Returns: (transfer none): a #GSequenceIter pointing somewhere in the - * (@begin, @end) range - * Since: 2.14 - */ - - -/** - * g_sequence_remove: - * @iter: a #GSequenceIter - * - * Removes the item pointed to by @iter. It is an error to pass the - * end iterator to this function. - * - * If the sequence has a data destroy function associated with it, this - * function is called on the data for the removed item. - * - * Since: 2.14 - */ - - -/** - * g_sequence_remove_range: - * @begin: a #GSequenceIter - * @end: a #GSequenceIter - * - * Removes all items in the (@begin, @end) range. - * - * If the sequence has a data destroy function associated with it, this - * function is called on the data for the removed items. - * - * Since: 2.14 - */ - - -/** - * g_sequence_search: - * @seq: a #GSequence - * @data: data for the new item - * @cmp_func: the function used to compare items in the sequence - * @cmp_data: user data passed to @cmp_func - * - * Returns an iterator pointing to the position where @data would - * be inserted according to @cmp_func and @cmp_data. - * - * @cmp_func is called with two items of the @seq, and @cmp_data. - * It should return 0 if the items are equal, a negative value if - * the first item comes before the second, and a positive value if - * the second item comes before the first. - * - * If you are simply searching for an existing element of the sequence, - * consider using g_sequence_lookup(). - * - * This function will fail if the data contained in the sequence is - * unsorted. - * - * Returns: (transfer none): an #GSequenceIter pointing to the position where @data - * would have been inserted according to @cmp_func and @cmp_data - * Since: 2.14 - */ - - -/** - * g_sequence_search_iter: - * @seq: a #GSequence - * @data: data for the new item - * @iter_cmp: the function used to compare iterators in the sequence - * @cmp_data: user data passed to @iter_cmp - * - * Like g_sequence_search(), but uses a #GSequenceIterCompareFunc - * instead of a #GCompareDataFunc as the compare function. - * - * @iter_cmp is called with two iterators pointing into @seq. - * It should return 0 if the iterators are equal, a negative value - * if the first iterator comes before the second, and a positive - * value if the second iterator comes before the first. - * - * If you are simply searching for an existing element of the sequence, - * consider using g_sequence_lookup_iter(). - * - * This function will fail if the data contained in the sequence is - * unsorted. - * - * Returns: (transfer none): a #GSequenceIter pointing to the position in @seq - * where @data would have been inserted according to @iter_cmp - * and @cmp_data - * Since: 2.14 - */ - - -/** - * g_sequence_set: - * @iter: a #GSequenceIter - * @data: new data for the item - * - * Changes the data for the item pointed to by @iter to be @data. If - * the sequence has a data destroy function associated with it, that - * function is called on the existing data that @iter pointed to. - * - * Since: 2.14 - */ - - -/** - * g_sequence_sort: - * @seq: a #GSequence - * @cmp_func: the function used to sort the sequence - * @cmp_data: user data passed to @cmp_func - * - * Sorts @seq using @cmp_func. - * - * @cmp_func is passed two items of @seq and should - * return 0 if they are equal, a negative value if the - * first comes before the second, and a positive value - * if the second comes before the first. - * - * Since: 2.14 - */ - - -/** - * g_sequence_sort_changed: - * @iter: A #GSequenceIter - * @cmp_func: the function used to compare items in the sequence - * @cmp_data: user data passed to @cmp_func. - * - * Moves the data pointed to by @iter to a new position as indicated by - * @cmp_func. This - * function should be called for items in a sequence already sorted according - * to @cmp_func whenever some aspect of an item changes so that @cmp_func - * may return different values for that item. - * - * @cmp_func is called with two items of the @seq, and @cmp_data. - * It should return 0 if the items are equal, a negative value if - * the first item comes before the second, and a positive value if - * the second item comes before the first. - * - * Since: 2.14 - */ - - -/** - * g_sequence_sort_changed_iter: - * @iter: a #GSequenceIter - * @iter_cmp: the function used to compare iterators in the sequence - * @cmp_data: user data passed to @cmp_func - * - * Like g_sequence_sort_changed(), but uses - * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as - * the compare function. - * - * @iter_cmp is called with two iterators pointing into the #GSequence that - * @iter points into. It should - * return 0 if the iterators are equal, a negative value if the first - * iterator comes before the second, and a positive value if the second - * iterator comes before the first. - * - * Since: 2.14 - */ - - -/** - * g_sequence_sort_iter: - * @seq: a #GSequence - * @cmp_func: the function used to compare iterators in the sequence - * @cmp_data: user data passed to @cmp_func - * - * Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead - * of a #GCompareDataFunc as the compare function - * - * @cmp_func is called with two iterators pointing into @seq. It should - * return 0 if the iterators are equal, a negative value if the first - * iterator comes before the second, and a positive value if the second - * iterator comes before the first. - * - * Since: 2.14 - */ - - -/** - * g_sequence_swap: - * @a: a #GSequenceIter - * @b: a #GSequenceIter - * - * Swaps the items pointed to by @a and @b. It is allowed for @a and @b - * to point into difference sequences. - * - * Since: 2.14 - */ - - -/** - * g_set_application_name: - * @application_name: localized name of the application - * - * Sets a human-readable name for the application. This name should be - * localized if possible, and is intended for display to the user. - * Contrast with g_set_prgname(), which sets a non-localized name. - * g_set_prgname() will be called automatically by gtk_init(), - * but g_set_application_name() will not. - * - * Note that for thread safety reasons, this function can only - * be called once. - * - * The application name will be used in contexts such as error messages, - * or when displaying an application's name in the task list. - * - * Since: 2.2 - */ - - -/** - * g_set_error: - * @err: (out callee-allocates) (optional): a return location for a #GError - * @domain: error domain - * @code: error code - * @format: printf()-style format - * @...: args for @format - * - * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err - * must be %NULL. A new #GError is created and assigned to *@err. - */ - - -/** - * g_set_error_literal: - * @err: (out callee-allocates) (optional): a return location for a #GError - * @domain: error domain - * @code: error code - * @message: error message - * - * Does nothing if @err is %NULL; if @err is non-%NULL, then *@err - * must be %NULL. A new #GError is created and assigned to *@err. - * Unlike g_set_error(), @message is not a printf()-style format string. - * Use this function if @message contains text you don't have control over, - * that could include printf() escape sequences. - * - * Since: 2.18 - */ - - -/** - * g_set_prgname: - * @prgname: the name of the program. - * - * Sets the name of the program. This name should not be localized, - * in contrast to g_set_application_name(). - * - * If you are using #GApplication the program name is set in - * g_application_run(). In case of GDK or GTK+ it is set in - * gdk_init(), which is called by gtk_init() and the - * #GtkApplication::startup handler. The program name is found by - * taking the last component of @argv[0]. - * - * Note that for thread-safety reasons this function can only be called once. - */ - - -/** - * g_set_print_handler: - * @func: the new print handler - * - * Sets the print handler. - * - * Any messages passed to g_print() will be output via - * the new handler. The default handler simply outputs - * the message to stdout. By providing your own handler - * you can redirect the output, to a GTK+ widget or a - * log file for example. - * - * Returns: the old print handler - */ - - -/** - * g_set_printerr_handler: - * @func: the new error message handler - * - * Sets the handler for printing error messages. - * - * Any messages passed to g_printerr() will be output via - * the new handler. The default handler simply outputs the - * message to stderr. By providing your own handler you can - * redirect the output, to a GTK+ widget or a log file for - * example. - * - * Returns: the old error message handler - */ - - -/** - * g_setenv: - * @variable: (type filename): the environment variable to set, must not - * contain '='. - * @value: (type filename): the value for to set the variable to. - * @overwrite: whether to change the variable if it already exists. - * - * Sets an environment variable. 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. - * - * Note that on some systems, when variables are overwritten, the memory - * used for the previous variables and its value isn't reclaimed. - * - * You should be mindful of the fact that environment variable handling - * in UNIX is not thread-safe, and your program may crash if one thread - * calls g_setenv() while another thread is calling getenv(). (And note - * that many functions, such as gettext(), call getenv() internally.) - * This function is only safe to use at the very start of your program, - * before creating any other threads (or creating objects that create - * worker threads of their own). - * - * If you need to set up the environment for a child process, you can - * use g_get_environ() to get an environment array, modify that with - * g_environ_setenv() and g_environ_unsetenv(), and then pass that - * array directly to execvpe(), g_spawn_async(), or the like. - * - * Returns: %FALSE if the environment variable couldn't be set. - * Since: 2.4 - */ - - -/** - * g_shell_parse_argv: - * @command_line: (type filename): command line to parse - * @argcp: (out) (optional): return location for number of args - * @argvp: (out) (optional) (array length=argcp zero-terminated=1) (element-type filename): - * return location for array of args - * @error: (optional): return location for error - * - * Parses a command line into an argument vector, in much the same way - * the shell would, but without many of the expansions the shell would - * perform (variable expansion, globs, operators, filename expansion, - * etc. are not supported). - * - * The results are defined to be the same as those you would get from - * a UNIX98 `/bin/sh`, as long as the input contains none of the - * unsupported shell expansions. If the input does contain such expansions, - * they are passed through literally. - * - * Possible errors are those from the %G_SHELL_ERROR domain. - * - * Free the returned vector with g_strfreev(). - * - * Returns: %TRUE on success, %FALSE if error set - */ - - -/** - * g_shell_quote: - * @unquoted_string: (type filename): a literal string - * - * Quotes a string so that the shell (/bin/sh) will interpret the - * quoted string to mean @unquoted_string. - * - * If you pass a filename to the shell, for example, you should first - * quote it with this function. - * - * The return value must be freed with g_free(). - * - * The quoting style used is undefined (single or double quotes may be - * used). - * - * Returns: (type filename) (transfer full): quoted string - */ - - -/** - * g_shell_unquote: - * @quoted_string: (type filename): shell-quoted string - * @error: error return location or NULL - * - * Unquotes a string as the shell (/bin/sh) would. - * - * This function only handles quotes; if a string contains file globs, - * arithmetic operators, variables, backticks, redirections, or other - * special-to-the-shell features, the result will be different from the - * result a real shell would produce (the variables, backticks, etc. - * will be passed through literally instead of being expanded). - * - * This function is guaranteed to succeed if applied to the result of - * g_shell_quote(). If it fails, it returns %NULL and sets the - * error. - * - * The @quoted_string need not actually contain quoted or escaped text; - * g_shell_unquote() simply goes through the string and unquotes/unescapes - * anything that the shell would. Both single and double quotes are - * handled, as are escapes including escaped newlines. - * - * The return value must be freed with g_free(). - * - * Possible errors are in the %G_SHELL_ERROR domain. - * - * Shell quoting rules are a bit strange. Single quotes preserve the - * literal string exactly. escape sequences are not allowed; not even - * `\'` - if you want a `'` in the quoted text, you have to do something - * like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and - * newline to be escaped with backslash. Otherwise double quotes - * preserve things literally. - * - * Returns: (type filename): an unquoted string - */ - - -/** - * g_size_checked_add: - * @dest: a pointer to the #gsize destination - * @a: the #gsize left operand - * @b: the #gsize right operand - * - * Performs a checked addition of @a and @b, storing the result in - * @dest. - * - * If the operation is successful, %TRUE is returned. If the operation - * overflows then the state of @dest is undefined and %FALSE is - * returned. - * - * Returns: %TRUE if there was no overflow - * Since: 2.48 - */ - - -/** - * g_size_checked_mul: - * @dest: a pointer to the #gsize destination - * @a: the #gsize left operand - * @b: the #gsize right operand - * - * Performs a checked multiplication of @a and @b, storing the result in - * @dest. - * - * If the operation is successful, %TRUE is returned. If the operation - * overflows then the state of @dest is undefined and %FALSE is - * returned. - * - * Returns: %TRUE if there was no overflow - * Since: 2.48 - */ - - -/** - * g_slice_alloc: - * @block_size: the number of bytes to allocate - * - * Allocates a block of memory from the slice allocator. - * - * The block address handed out can be expected to be aligned - * to at least `1 * sizeof (void*)`, though in general slices - * are `2 * sizeof (void*)` bytes aligned; if a `malloc()` - * fallback implementation is used instead, the alignment may - * be reduced in a libc dependent fashion. - * - * Note that the underlying slice allocation mechanism can - * be changed with the [`G_SLICE=always-malloc`][G_SLICE] - * environment variable. - * - * Returns: a pointer to the allocated memory block, which will - * be %NULL if and only if @mem_size is 0 - * Since: 2.10 - */ - - -/** - * g_slice_alloc0: - * @block_size: the number of bytes to allocate - * - * Allocates a block of memory via g_slice_alloc() and initializes - * the returned memory to 0. Note that the underlying slice allocation - * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] - * environment variable. - * - * Returns: a pointer to the allocated block, which will be %NULL if and only - * if @mem_size is 0 - * Since: 2.10 - */ - - -/** - * g_slice_copy: - * @block_size: the number of bytes to allocate - * @mem_block: the memory to copy - * - * Allocates a block of memory from the slice allocator - * and copies @block_size bytes into it from @mem_block. - * - * @mem_block must be non-%NULL if @block_size is non-zero. - * - * Returns: a pointer to the allocated memory block, which will be %NULL if and - * only if @mem_size is 0 - * Since: 2.14 - */ - - -/** - * g_slice_dup: - * @type: the type to duplicate, typically a structure name - * @mem: (not nullable): the memory to copy into the allocated block - * - * A convenience macro to duplicate a block of memory using - * the slice allocator. - * - * It calls g_slice_copy() with `sizeof (@type)` - * and casts the returned pointer to a pointer of the given type, - * avoiding a type cast in the source code. - * Note that the underlying slice allocation mechanism can - * be changed with the [`G_SLICE=always-malloc`][G_SLICE] - * environment variable. - * - * This can never return %NULL. - * - * Returns: (not nullable): a pointer to the allocated block, cast to a pointer - * to @type - * Since: 2.14 - */ - - -/** - * g_slice_free: - * @type: the type of the block to free, typically a structure name - * @mem: a pointer to the block to free - * - * A convenience macro to free a block of memory that has - * been allocated from the slice allocator. - * - * It calls g_slice_free1() using `sizeof (type)` - * as the block size. - * Note that the exact release behaviour can be changed with the - * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see - * [`G_SLICE`][G_SLICE] for related debugging options. - * - * If @mem is %NULL, this macro does nothing. - * - * Since: 2.10 - */ - - -/** - * g_slice_free1: - * @block_size: the size of the block - * @mem_block: a pointer to the block to free - * - * Frees a block of memory. - * - * The memory must have been allocated via g_slice_alloc() or - * g_slice_alloc0() and the @block_size has to match the size - * specified upon allocation. Note that the exact release behaviour - * can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment - * variable, also see [`G_SLICE`][G_SLICE] for related debugging options. - * - * If @mem_block is %NULL, this function does nothing. - * - * Since: 2.10 - */ - - -/** - * g_slice_free_chain: - * @type: the type of the @mem_chain blocks - * @mem_chain: a pointer to the first block of the chain - * @next: the field name of the next pointer in @type - * - * Frees a linked list of memory blocks of structure type @type. - * - * The memory blocks must be equal-sized, allocated via - * g_slice_alloc() or g_slice_alloc0() and linked together by - * a @next pointer (similar to #GSList). The name of the - * @next field in @type is passed as third argument. - * Note that the exact release behaviour can be changed with the - * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see - * [`G_SLICE`][G_SLICE] for related debugging options. - * - * If @mem_chain is %NULL, this function does nothing. - * - * Since: 2.10 - */ - - -/** - * g_slice_free_chain_with_offset: - * @block_size: the size of the blocks - * @mem_chain: a pointer to the first block of the chain - * @next_offset: the offset of the @next field in the blocks - * - * Frees a linked list of memory blocks of structure type @type. - * - * The memory blocks must be equal-sized, allocated via - * g_slice_alloc() or g_slice_alloc0() and linked together by a - * @next pointer (similar to #GSList). The offset of the @next - * field in each block is passed as third argument. - * Note that the exact release behaviour can be changed with the - * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see - * [`G_SLICE`][G_SLICE] for related debugging options. - * - * If @mem_chain is %NULL, this function does nothing. - * - * Since: 2.10 - */ - - -/** - * g_slice_new: - * @type: the type to allocate, typically a structure name - * - * A convenience macro to allocate a block of memory from the - * slice allocator. - * - * It calls g_slice_alloc() with `sizeof (@type)` and casts the - * returned pointer to a pointer of the given type, avoiding a type - * cast in the source code. Note that the underlying slice allocation - * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] - * environment variable. - * - * This can never return %NULL as the minimum allocation size from - * `sizeof (@type)` is 1 byte. - * - * Returns: (not nullable): a pointer to the allocated block, cast to a pointer - * to @type - * Since: 2.10 - */ - - -/** - * g_slice_new0: - * @type: the type to allocate, typically a structure name - * - * A convenience macro to allocate a block of memory from the - * slice allocator and set the memory to 0. - * - * It calls g_slice_alloc0() with `sizeof (@type)` - * and casts the returned pointer to a pointer of the given type, - * avoiding a type cast in the source code. - * Note that the underlying slice allocation mechanism can - * be changed with the [`G_SLICE=always-malloc`][G_SLICE] - * environment variable. - * - * This can never return %NULL as the minimum allocation size from - * `sizeof (@type)` is 1 byte. - * - * Returns: (not nullable): a pointer to the allocated block, cast to a pointer - * to @type - * Since: 2.10 - */ - - -/** - * g_slist_alloc: - * - * Allocates space for one #GSList element. It is called by the - * g_slist_append(), g_slist_prepend(), g_slist_insert() and - * g_slist_insert_sorted() functions and so is rarely used on its own. - * - * Returns: a pointer to the newly-allocated #GSList element. - */ - - -/** - * g_slist_append: - * @list: a #GSList - * @data: the data for the new element - * - * Adds a new element on to the end of the list. - * - * The return value is the new start of the list, which may - * have changed, so make sure you store the new value. - * - * Note that g_slist_append() has to traverse the entire list - * to find the end, which is inefficient when adding multiple - * elements. A common idiom to avoid the inefficiency is to prepend - * the elements and reverse the list when all elements have been added. - * - * |[<!-- language="C" --> - * // Notice that these are initialized to the empty list. - * GSList *list = NULL, *number_list = NULL; - * - * // This is a list of strings. - * list = g_slist_append (list, "first"); - * list = g_slist_append (list, "second"); - * - * // This is a list of integers. - * number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); - * number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); - * ]| - * - * Returns: the new start of the #GSList - */ - - -/** - * g_slist_concat: - * @list1: a #GSList - * @list2: the #GSList to add to the end of the first #GSList - * - * Adds the second #GSList onto the end of the first #GSList. - * Note that the elements of the second #GSList are not copied. - * They are used directly. - * - * Returns: the start of the new #GSList - */ - - -/** - * g_slist_copy: - * @list: a #GSList - * - * Copies a #GSList. - * - * Note that this is a "shallow" copy. If the list elements - * consist of pointers to data, the pointers are copied but - * the actual data isn't. See g_slist_copy_deep() if you need - * to copy the data as well. - * - * Returns: a copy of @list - */ - - -/** - * g_slist_copy_deep: - * @list: a #GSList - * @func: a copy function used to copy every element in the list - * @user_data: user data passed to the copy function @func, or #NULL - * - * Makes a full (deep) copy of a #GSList. - * - * In contrast with g_slist_copy(), this function uses @func to make a copy of - * each list element, in addition to copying the list container itself. - * - * @func, as a #GCopyFunc, takes two arguments, the data to be copied - * and a @user_data pointer. On common processor architectures, it's safe to - * pass %NULL as @user_data if the copy function takes only one argument. You - * may get compiler warnings from this though if compiling with GCC’s - * `-Wcast-function-type` warning. - * - * For instance, if @list holds a list of GObjects, you can do: - * |[<!-- language="C" --> - * another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL); - * ]| - * - * And, to entirely free the new list, you could do: - * |[<!-- language="C" --> - * g_slist_free_full (another_list, g_object_unref); - * ]| - * - * Returns: a full copy of @list, use g_slist_free_full() to free it - * Since: 2.34 - */ - - -/** - * g_slist_delete_link: - * @list: a #GSList - * @link_: node to delete - * - * Removes the node link_ from the list and frees it. - * Compare this to g_slist_remove_link() which removes the node - * without freeing it. - * - * Removing arbitrary nodes from a singly-linked list requires time - * that is proportional to the length of the list (ie. O(n)). If you - * find yourself using g_slist_delete_link() frequently, you should - * consider a different data structure, such as the doubly-linked - * #GList. - * - * Returns: the new head of @list - */ - - -/** - * g_slist_find: - * @list: a #GSList - * @data: the element data to find - * - * Finds the element in a #GSList which - * contains the given data. - * - * Returns: the found #GSList element, - * or %NULL if it is not found - */ - - -/** - * g_slist_find_custom: - * @list: a #GSList - * @data: user data passed to the function - * @func: the function to call for each element. - * It should return 0 when the desired element is found - * - * Finds an element in a #GSList, using a supplied function to - * find the desired element. It iterates over the list, calling - * the given function which should return 0 when the desired - * element is found. The function takes two #gconstpointer arguments, - * the #GSList element's data as the first argument and the - * given user data. - * - * Returns: the found #GSList element, or %NULL if it is not found - */ - - -/** - * g_slist_foreach: - * @list: a #GSList - * @func: the function to call with each element's data - * @user_data: user data to pass to the function - * - * Calls a function for each element of a #GSList. - * - * It is safe for @func to remove the element from @list, but it must - * not modify any part of the list after that element. - */ - - -/** - * g_slist_free: - * @list: the first link of a #GSList - * - * Frees all of the memory used by a #GSList. - * The freed elements are returned to the slice allocator. - * - * If list elements contain dynamically-allocated memory, - * you should either use g_slist_free_full() or free them manually - * first. - * - * It can be combined with g_steal_pointer() to ensure the list head pointer - * is not left dangling: - * |[<!-- language="C" --> - * GSList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/ - * g_slist_free (g_steal_pointer (&list_of_borrowed_things)); - * ]| - */ - - -/** - * g_slist_free1: - * - * A macro which does the same as g_slist_free_1(). - * - * Since: 2.10 - */ - - -/** - * g_slist_free_1: - * @list: a #GSList element - * - * Frees one #GSList element. - * It is usually used after g_slist_remove_link(). - */ - - -/** - * g_slist_free_full: - * @list: the first link of a #GSList - * @free_func: the function to be called to free each element's data - * - * Convenience method, which frees all the memory used by a #GSList, and - * calls the specified destroy function on every element's data. - * - * @free_func must not modify the list (eg, by removing the freed - * element from it). - * - * It can be combined with g_steal_pointer() to ensure the list head pointer - * is not left dangling — this also has the nice property that the head pointer - * is cleared before any of the list elements are freed, to prevent double frees - * from @free_func: - * |[<!-- language="C" --> - * GSList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/ - * g_slist_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref); - * ]| - * - * Since: 2.28 - */ - - -/** - * g_slist_index: - * @list: a #GSList - * @data: the data to find - * - * Gets the position of the element containing - * the given data (starting from 0). - * - * Returns: the index of the element containing the data, - * or -1 if the data is not found - */ - - -/** - * g_slist_insert: - * @list: a #GSList - * @data: the data for the new element - * @position: the position to insert the element. - * If this is negative, or is larger than the number - * of elements in the list, the new element is added on - * to the end of the list. - * - * Inserts a new element into the list at the given position. - * - * Returns: the new start of the #GSList - */ - - -/** - * g_slist_insert_before: - * @slist: a #GSList - * @sibling: node to insert @data before - * @data: data to put in the newly-inserted node - * - * Inserts a node before @sibling containing @data. - * - * Returns: the new head of the list. - */ - - -/** - * g_slist_insert_sorted: - * @list: a #GSList - * @data: the data for the new element - * @func: the function to compare elements in the list. - * It should return a number > 0 if the first parameter - * comes after the second parameter in the sort order. - * - * Inserts a new element into the list, using the given - * comparison function to determine its position. - * - * Returns: the new start of the #GSList - */ - - -/** - * g_slist_insert_sorted_with_data: - * @list: a #GSList - * @data: the data for the new element - * @func: the function to compare elements in the list. - * It should return a number > 0 if the first parameter - * comes after the second parameter in the sort order. - * @user_data: data to pass to comparison function - * - * Inserts a new element into the list, using the given - * comparison function to determine its position. - * - * Returns: the new start of the #GSList - * Since: 2.10 - */ - - -/** - * g_slist_last: - * @list: a #GSList - * - * Gets the last element in a #GSList. - * - * This function iterates over the whole list. - * - * Returns: the last element in the #GSList, - * or %NULL if the #GSList has no elements - */ - - -/** - * g_slist_length: - * @list: a #GSList - * - * Gets the number of elements in a #GSList. - * - * This function iterates over the whole list to - * count its elements. To check whether the list is non-empty, it is faster to - * check @list against %NULL. - * - * Returns: the number of elements in the #GSList - */ - - -/** - * g_slist_next: - * @slist: an element in a #GSList. - * - * A convenience macro to get the next element in a #GSList. - * Note that it is considered perfectly acceptable to access - * @slist->next directly. - * - * Returns: the next element, or %NULL if there are no more elements. - */ - - -/** - * g_slist_nth: - * @list: a #GSList - * @n: the position of the element, counting from 0 - * - * Gets the element at the given position in a #GSList. - * - * Returns: the element, or %NULL if the position is off - * the end of the #GSList - */ - - -/** - * g_slist_nth_data: - * @list: a #GSList - * @n: the position of the element - * - * Gets the data of the element at the given position. - * - * Returns: the element's data, or %NULL if the position - * is off the end of the #GSList - */ - - -/** - * g_slist_position: - * @list: a #GSList - * @llink: an element in the #GSList - * - * Gets the position of the given element - * in the #GSList (starting from 0). - * - * Returns: the position of the element in the #GSList, - * or -1 if the element is not found - */ - - -/** - * g_slist_prepend: - * @list: a #GSList - * @data: the data for the new element - * - * Adds a new element on to the start of the list. - * - * The return value is the new start of the list, which - * may have changed, so make sure you store the new value. - * - * |[<!-- language="C" --> - * // Notice that it is initialized to the empty list. - * GSList *list = NULL; - * list = g_slist_prepend (list, "last"); - * list = g_slist_prepend (list, "first"); - * ]| - * - * Returns: the new start of the #GSList - */ - - -/** - * g_slist_remove: - * @list: a #GSList - * @data: the data of the element to remove - * - * Removes an element from a #GSList. - * If two elements contain the same data, only the first is removed. - * If none of the elements contain the data, the #GSList is unchanged. - * - * Returns: the new start of the #GSList - */ - - -/** - * g_slist_remove_all: - * @list: a #GSList - * @data: data to remove - * - * Removes all list nodes with data equal to @data. - * Returns the new head of the list. Contrast with - * g_slist_remove() which removes only the first node - * matching the given data. - * - * Returns: new head of @list - */ - - -/** - * g_slist_remove_link: - * @list: a #GSList - * @link_: an element in the #GSList - * - * Removes an element from a #GSList, without - * freeing the element. The removed element's next - * link is set to %NULL, so that it becomes a - * self-contained list with one element. - * - * Removing arbitrary nodes from a singly-linked list - * requires time that is proportional to the length of the list - * (ie. O(n)). If you find yourself using g_slist_remove_link() - * frequently, you should consider a different data structure, - * such as the doubly-linked #GList. - * - * Returns: the new start of the #GSList, without the element - */ - - -/** - * g_slist_reverse: - * @list: a #GSList - * - * Reverses a #GSList. - * - * Returns: the start of the reversed #GSList - */ - - -/** - * g_slist_sort: - * @list: a #GSList - * @compare_func: the comparison function used to sort the #GSList. - * This function is passed the data from 2 elements of the #GSList - * and should return 0 if they are equal, a negative value if the - * first element comes before the second, or a positive value if - * the first element comes after the second. - * - * Sorts a #GSList using the given comparison function. The algorithm - * used is a stable sort. - * - * Returns: the start of the sorted #GSList - */ - - -/** - * g_slist_sort_with_data: - * @list: a #GSList - * @compare_func: comparison function - * @user_data: data to pass to comparison function - * - * Like g_slist_sort(), but the sort function accepts a user data argument. - * - * Returns: new head of the list - */ - - -/** - * g_snprintf: - * @string: the buffer to hold the output. - * @n: the maximum number of bytes to produce (including the - * terminating nul character). - * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] - * @...: the arguments to insert in the output. - * - * A safer form of the standard sprintf() function. The output is guaranteed - * to not exceed @n characters (including the terminating nul character), so - * it is easy to ensure that a buffer overflow cannot occur. - * - * See also g_strdup_printf(). - * - * In versions of GLib prior to 1.2.3, this function may return -1 if the - * output was truncated, and the truncated string may not be nul-terminated. - * In versions prior to 1.3.12, this function returns the length of the output - * string. - * - * The return value of g_snprintf() conforms to the snprintf() - * function as standardized in ISO C99. Note that this is different from - * traditional snprintf(), which returns the length of the output string. - * - * The format string may contain positional parameters, as specified in - * the Single Unix Specification. - * - * Returns: the number of bytes which would be produced if the buffer - * was large enough. - */ - - -/** - * g_source_add_child_source: - * @source: a #GSource - * @child_source: a second #GSource that @source should "poll" - * - * Adds @child_source to @source as a "polled" source; when @source is - * added to a #GMainContext, @child_source will be automatically added - * with the same priority, when @child_source is triggered, it will - * cause @source to dispatch (in addition to calling its own - * callback), and when @source is destroyed, it will destroy - * @child_source as well. (@source will also still be dispatched if - * its own prepare/check functions indicate that it is ready.) - * - * If you don't need @child_source to do anything on its own when it - * triggers, you can call g_source_set_dummy_callback() on it to set a - * callback that does nothing (except return %TRUE if appropriate). - * - * @source will hold a reference on @child_source while @child_source - * is attached to it. - * - * This API is only intended to be used by implementations of #GSource. - * Do not call this API on a #GSource that you did not create. - * - * Since: 2.28 - */ - - -/** - * g_source_add_poll: - * @source: a #GSource - * @fd: a #GPollFD structure holding information about a file - * descriptor to watch. - * - * Adds a file descriptor to the set of file descriptors polled for - * this source. This is usually combined with g_source_new() to add an - * event source. The event source's check function will typically test - * the @revents field in the #GPollFD struct and return %TRUE if events need - * to be processed. - * - * This API is only intended to be used by implementations of #GSource. - * Do not call this API on a #GSource that you did not create. - * - * Using this API forces the linear scanning of event sources on each - * main loop iteration. Newly-written event sources should try to use - * g_source_add_unix_fd() instead of this API. - */ - - -/** - * g_source_add_unix_fd: - * @source: a #GSource - * @fd: the fd to monitor - * @events: an event mask - * - * Monitors @fd for the IO events in @events. - * - * The tag returned by this function can be used to remove or modify the - * monitoring of the fd using g_source_remove_unix_fd() or - * g_source_modify_unix_fd(). - * - * It is not necessary to remove the fd before destroying the source; it - * will be cleaned up automatically. - * - * This API is only intended to be used by implementations of #GSource. - * Do not call this API on a #GSource that you did not create. - * - * As the name suggests, this function is not available on Windows. - * - * Returns: (not nullable): an opaque tag - * Since: 2.36 - */ - - -/** - * g_source_attach: - * @source: a #GSource - * @context: (nullable): a #GMainContext (if %NULL, the default context will be used) - * - * Adds a #GSource to a @context so that it will be executed within - * that context. Remove it by calling g_source_destroy(). - * - * This function is safe to call from any thread, regardless of which thread - * the @context is running in. - * - * Returns: the ID (greater than 0) for the source within the - * #GMainContext. - */ - - -/** - * g_source_destroy: - * @source: a #GSource - * - * Removes a source from its #GMainContext, if any, and mark it as - * destroyed. The source cannot be subsequently added to another - * context. It is safe to call this on sources which have already been - * removed from their context. - * - * This does not unref the #GSource: if you still hold a reference, use - * g_source_unref() to drop it. - * - * This function is safe to call from any thread, regardless of which thread - * the #GMainContext is running in. - * - * If the source is currently attached to a #GMainContext, destroying it - * will effectively unset the callback similar to calling g_source_set_callback(). - * This can mean, that the data's #GDestroyNotify gets called right away. - */ - - -/** - * g_source_get_can_recurse: - * @source: a #GSource - * - * Checks whether a source is allowed to be called recursively. - * see g_source_set_can_recurse(). - * - * Returns: whether recursion is allowed. - */ - - -/** - * g_source_get_context: - * @source: a #GSource - * - * Gets the #GMainContext with which the source is associated. - * - * You can call this on a source that has been destroyed, provided - * that the #GMainContext it was attached to still exists (in which - * case it will return that #GMainContext). In particular, you can - * always call this function on the source returned from - * g_main_current_source(). But calling this function on a source - * whose #GMainContext has been destroyed is an error. - * - * Returns: (transfer none) (nullable): the #GMainContext with which the - * source is associated, or %NULL if the context has not - * yet been added to a source. - */ - - -/** - * g_source_get_current_time: - * @source: a #GSource - * @timeval: #GTimeVal structure in which to store current time. - * - * This function ignores @source and is otherwise the same as - * g_get_current_time(). - * - * Deprecated: 2.28: use g_source_get_time() instead - */ - - -/** - * g_source_get_id: - * @source: a #GSource - * - * Returns the numeric ID for a particular source. The ID of a source - * is a positive integer which is unique within a particular main loop - * context. The reverse - * mapping from ID to source is done by g_main_context_find_source_by_id(). - * - * You can only call this function while the source is associated to a - * #GMainContext instance; calling this function before g_source_attach() - * or after g_source_destroy() yields undefined behavior. The ID returned - * is unique within the #GMainContext instance passed to g_source_attach(). - * - * Returns: the ID (greater than 0) for the source - */ - - -/** - * g_source_get_name: - * @source: a #GSource - * - * Gets a name for the source, used in debugging and profiling. The - * name may be #NULL if it has never been set with g_source_set_name(). - * - * Returns: (nullable): the name of the source - * Since: 2.26 - */ - - -/** - * g_source_get_priority: - * @source: a #GSource - * - * Gets the priority of a source. - * - * Returns: the priority of the source - */ - - -/** - * g_source_get_ready_time: - * @source: a #GSource - * - * Gets the "ready time" of @source, as set by - * g_source_set_ready_time(). - * - * Any time before the current monotonic time (including 0) is an - * indication that the source will fire immediately. - * - * Returns: the monotonic ready time, -1 for "never" - */ - - -/** - * g_source_get_time: - * @source: a #GSource - * - * Gets the time to be used when checking this source. The advantage of - * calling this function over calling g_get_monotonic_time() directly is - * that when checking multiple sources, GLib can cache a single value - * instead of having to repeatedly get the system monotonic time. - * - * The time here is the system monotonic time, if available, or some - * other reasonable alternative otherwise. See g_get_monotonic_time(). - * - * Returns: the monotonic time in microseconds - * Since: 2.28 - */ - - -/** - * g_source_is_destroyed: - * @source: a #GSource - * - * Returns whether @source has been destroyed. - * - * This is important when you operate upon your objects - * from within idle handlers, but may have freed the object - * before the dispatch of your idle handler. - * - * |[<!-- language="C" --> - * static gboolean - * idle_callback (gpointer data) - * { - * SomeWidget *self = data; - * - * g_mutex_lock (&self->idle_id_mutex); - * // do stuff with self - * self->idle_id = 0; - * g_mutex_unlock (&self->idle_id_mutex); - * - * return G_SOURCE_REMOVE; - * } - * - * static void - * some_widget_do_stuff_later (SomeWidget *self) - * { - * g_mutex_lock (&self->idle_id_mutex); - * self->idle_id = g_idle_add (idle_callback, self); - * g_mutex_unlock (&self->idle_id_mutex); - * } - * - * static void - * some_widget_init (SomeWidget *self) - * { - * g_mutex_init (&self->idle_id_mutex); - * - * // ... - * } - * - * static void - * some_widget_finalize (GObject *object) - * { - * SomeWidget *self = SOME_WIDGET (object); - * - * if (self->idle_id) - * g_source_remove (self->idle_id); - * - * g_mutex_clear (&self->idle_id_mutex); - * - * G_OBJECT_CLASS (parent_class)->finalize (object); - * } - * ]| - * - * This will fail in a multi-threaded application if the - * widget is destroyed before the idle handler fires due - * to the use after free in the callback. A solution, to - * this particular problem, is to check to if the source - * has already been destroy within the callback. - * - * |[<!-- language="C" --> - * static gboolean - * idle_callback (gpointer data) - * { - * SomeWidget *self = data; - * - * g_mutex_lock (&self->idle_id_mutex); - * if (!g_source_is_destroyed (g_main_current_source ())) - * { - * // do stuff with self - * } - * g_mutex_unlock (&self->idle_id_mutex); - * - * return FALSE; - * } - * ]| - * - * Calls to this function from a thread other than the one acquired by the - * #GMainContext the #GSource is attached to are typically redundant, as the - * source could be destroyed immediately after this function returns. However, - * once a source is destroyed it cannot be un-destroyed, so this function can be - * used for opportunistic checks from any thread. - * - * Returns: %TRUE if the source has been destroyed - * Since: 2.12 - */ - - -/** - * g_source_modify_unix_fd: - * @source: a #GSource - * @tag: (not nullable): the tag from g_source_add_unix_fd() - * @new_events: the new event mask to watch - * - * Updates the event mask to watch for the fd identified by @tag. - * - * @tag is the tag returned from g_source_add_unix_fd(). - * - * If you want to remove a fd, don't set its event mask to zero. - * Instead, call g_source_remove_unix_fd(). - * - * This API is only intended to be used by implementations of #GSource. - * Do not call this API on a #GSource that you did not create. - * - * As the name suggests, this function is not available on Windows. - * - * Since: 2.36 - */ - - -/** - * g_source_new: - * @source_funcs: structure containing functions that implement - * the sources behavior. - * @struct_size: size of the #GSource structure to create. - * - * Creates a new #GSource structure. The size is specified to - * allow creating structures derived from #GSource that contain - * additional data. The size passed in must be at least - * `sizeof (GSource)`. - * - * 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. - * - * Returns: the newly-created #GSource. - */ - - -/** - * g_source_query_unix_fd: - * @source: a #GSource - * @tag: (not nullable): the tag from g_source_add_unix_fd() - * - * Queries the events reported for the fd corresponding to @tag on - * @source during the last poll. - * - * The return value of this function is only defined when the function - * is called from the check or dispatch functions for @source. - * - * This API is only intended to be used by implementations of #GSource. - * Do not call this API on a #GSource that you did not create. - * - * As the name suggests, this function is not available on Windows. - * - * Returns: the conditions reported on the fd - * Since: 2.36 - */ - - -/** - * g_source_ref: - * @source: a #GSource - * - * Increases the reference count on a source by one. - * - * Returns: @source - */ - - -/** - * g_source_remove: - * @tag: the ID of the source to remove. - * - * Removes the source with the given ID from the default main context. You must - * use g_source_destroy() for sources added to a non-default main context. - * - * The ID of a #GSource is given by g_source_get_id(), or will be - * returned by the functions g_source_attach(), g_idle_add(), - * g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), - * g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and - * g_io_add_watch_full(). - * - * It is a programmer error to attempt to remove a non-existent source. - * - * More specifically: source IDs can be reissued after a source has been - * destroyed and therefore it is never valid to use this function with a - * source ID which may have already been removed. An example is when - * scheduling an idle to run in another thread with g_idle_add(): the - * idle may already have run and been removed by the time this function - * is called on its (now invalid) source ID. This source ID may have - * been reissued, leading to the operation being performed against the - * wrong source. - * - * Returns: For historical reasons, this function always returns %TRUE - */ - - -/** - * g_source_remove_by_funcs_user_data: - * @funcs: The @source_funcs passed to g_source_new() - * @user_data: the user data for the callback - * - * Removes a source from the default main loop context given the - * source functions and user data. If multiple sources exist with the - * same source functions and user data, only one will be destroyed. - * - * Returns: %TRUE if a source was found and removed. - */ - - -/** - * g_source_remove_by_user_data: - * @user_data: the user_data for the callback. - * - * Removes a source from the default main loop context given the user - * data for the callback. If multiple sources exist with the same user - * data, only one will be destroyed. - * - * Returns: %TRUE if a source was found and removed. - */ - - -/** - * g_source_remove_child_source: - * @source: a #GSource - * @child_source: a #GSource previously passed to - * g_source_add_child_source(). - * - * Detaches @child_source from @source and destroys it. - * - * This API is only intended to be used by implementations of #GSource. - * Do not call this API on a #GSource that you did not create. - * - * Since: 2.28 - */ - - -/** - * g_source_remove_poll: - * @source: a #GSource - * @fd: a #GPollFD structure previously passed to g_source_add_poll(). - * - * Removes a file descriptor from the set of file descriptors polled for - * this source. - * - * This API is only intended to be used by implementations of #GSource. - * Do not call this API on a #GSource that you did not create. - */ - - -/** - * g_source_remove_unix_fd: - * @source: a #GSource - * @tag: (not nullable): the tag from g_source_add_unix_fd() - * - * Reverses the effect of a previous call to g_source_add_unix_fd(). - * - * You only need to call this if you want to remove an fd from being - * watched while keeping the same source around. In the normal case you - * will just want to destroy the source. - * - * This API is only intended to be used by implementations of #GSource. - * Do not call this API on a #GSource that you did not create. - * - * As the name suggests, this function is not available on Windows. - * - * Since: 2.36 - */ - - -/** - * g_source_set_callback: - * @source: the source - * @func: a callback function - * @data: the data to pass to callback function - * @notify: (nullable): a function to call when @data is no longer in use, or %NULL. - * - * Sets the callback function for a source. The callback for a source is - * called from the source's dispatch function. - * - * The exact type of @func depends on the type of source; ie. you - * should not count on @func being called with @data as its first - * parameter. Cast @func with G_SOURCE_FUNC() to avoid warnings about - * incompatible function types. - * - * See [memory management of sources][mainloop-memory-management] for details - * on how to handle memory management of @data. - * - * Typically, you won't use this function. Instead use functions specific - * to the type of source you are using, such as g_idle_add() or g_timeout_add(). - * - * It is safe to call this function multiple times on a source which has already - * been attached to a context. The changes will take effect for the next time - * the source is dispatched after this call returns. - * - * Note that g_source_destroy() for a currently attached source has the effect - * of also unsetting the callback. - */ - - -/** - * g_source_set_callback_indirect: - * @source: the source - * @callback_data: pointer to callback data "object" - * @callback_funcs: functions for reference counting @callback_data - * and getting the callback and data - * - * Sets the callback function storing the data as a refcounted callback - * "object". This is used internally. Note that calling - * g_source_set_callback_indirect() assumes - * an initial reference count on @callback_data, and thus - * @callback_funcs->unref will eventually be called once more - * than @callback_funcs->ref. - * - * It is safe to call this function multiple times on a source which has already - * been attached to a context. The changes will take effect for the next time - * the source is dispatched after this call returns. - */ - - -/** - * g_source_set_can_recurse: - * @source: a #GSource - * @can_recurse: whether recursion is allowed for this source - * - * Sets whether a source can be called recursively. If @can_recurse is - * %TRUE, then while the source is being dispatched then this source - * will be processed normally. Otherwise, all processing of this - * source is blocked until the dispatch function returns. - */ - - -/** - * g_source_set_dispose_function: - * @source: A #GSource to set the dispose function on - * @dispose: #GSourceDisposeFunc to set on the source - * - * Set @dispose as dispose function on @source. @dispose will be called once - * the reference count of @source reaches 0 but before any of the state of the - * source is freed, especially before the finalize function is called. - * - * This means that at this point @source is still a valid #GSource and it is - * allow for the reference count to increase again until @dispose returns. - * - * The dispose function can be used to clear any "weak" references to the - * @source in other data structures in a thread-safe way where it is possible - * for another thread to increase the reference count of @source again while - * it is being freed. - * - * The finalize function can not be used for this purpose as at that point - * @source is already partially freed and not valid anymore. - * - * This should only ever be called from #GSource implementations. - * - * Since: 2.64 - */ - - -/** - * g_source_set_funcs: - * @source: a #GSource - * @funcs: the new #GSourceFuncs - * - * Sets the source functions (can be used to override - * default implementations) of an unattached source. - * - * Since: 2.12 - */ - - -/** - * g_source_set_name: - * @source: a #GSource - * @name: debug name for the source - * - * Sets a name for the source, used in debugging and profiling. - * The name defaults to #NULL. - * - * The source name should describe in a human-readable way - * what the source does. For example, "X11 event queue" - * or "GTK+ repaint idle handler" or whatever it is. - * - * It is permitted to call this function multiple times, but is not - * recommended due to the potential performance impact. For example, - * one could change the name in the "check" function of a #GSourceFuncs - * to include details like the event type in the source name. - * - * Use caution if changing the name while another thread may be - * accessing it with g_source_get_name(); that function does not copy - * the value, and changing the value will free it while the other thread - * may be attempting to use it. - * - * Also see g_source_set_static_name(). - * - * Since: 2.26 - */ - - -/** - * g_source_set_name_by_id: - * @tag: a #GSource ID - * @name: debug name for the source - * - * Sets the name of a source using its ID. - * - * This is a convenience utility to set source names from the return - * value of g_idle_add(), g_timeout_add(), etc. - * - * It is a programmer error to attempt to set the name of a non-existent - * source. - * - * More specifically: source IDs can be reissued after a source has been - * destroyed and therefore it is never valid to use this function with a - * source ID which may have already been removed. An example is when - * scheduling an idle to run in another thread with g_idle_add(): the - * idle may already have run and been removed by the time this function - * is called on its (now invalid) source ID. This source ID may have - * been reissued, leading to the operation being performed against the - * wrong source. - * - * Since: 2.26 - */ - - -/** - * g_source_set_priority: - * @source: a #GSource - * @priority: the new priority. - * - * Sets the priority of a source. While the main loop is being run, a - * source will be dispatched if it is ready to be dispatched and no - * sources at a higher (numerically smaller) priority are ready to be - * dispatched. - * - * A child source always has the same priority as its parent. It is not - * permitted to change the priority of a source once it has been added - * as a child of another source. - */ - - -/** - * g_source_set_ready_time: - * @source: a #GSource - * @ready_time: the monotonic time at which the source will be ready, - * 0 for "immediately", -1 for "never" - * - * Sets a #GSource to be dispatched when the given monotonic time is - * reached (or passed). If the monotonic time is in the past (as it - * always will be if @ready_time is 0) then the source will be - * dispatched immediately. - * - * If @ready_time is -1 then the source is never woken up on the basis - * of the passage of time. - * - * Dispatching the source does not reset the ready time. You should do - * so yourself, from the source dispatch function. - * - * Note that if you have a pair of sources where the ready time of one - * suggests that it will be delivered first but the priority for the - * other suggests that it would be delivered first, and the ready time - * for both sources is reached during the same main context iteration, - * then the order of dispatch is undefined. - * - * It is a no-op to call this function on a #GSource which has already been - * destroyed with g_source_destroy(). - * - * This API is only intended to be used by implementations of #GSource. - * Do not call this API on a #GSource that you did not create. - * - * Since: 2.36 - */ - - -/** - * g_source_set_static_name: - * @source: a #GSource - * @name: debug name for the source - * - * A variant of g_source_set_name() that does not - * duplicate the @name, and can only be used with - * string literals. - * - * Since: 2.70 - */ - - -/** - * g_source_unref: - * @source: a #GSource - * - * Decreases the reference count of a source by one. If the - * resulting reference count is zero the source and associated - * memory will be destroyed. - */ - - -/** - * g_spaced_primes_closest: - * @num: a #guint - * - * Gets the smallest prime number from a built-in array of primes which - * is larger than @num. This is used within GLib to calculate the optimum - * size of a #GHashTable. - * - * The built-in array of primes ranges from 11 to 13845163 such that - * each prime is approximately 1.5-2 times the previous prime. - * - * Returns: the smallest prime number from a built-in array of primes - * which is larger than @num - */ - - -/** - * g_spawn_async: - * @working_directory: (type filename) (nullable): child's current working - * directory, or %NULL to inherit parent's - * @argv: (array zero-terminated=1) (element-type filename): - * child's argument vector - * @envp: (array zero-terminated=1) (element-type filename) (nullable): - * child's environment, or %NULL to inherit parent's - * @flags: flags from #GSpawnFlags - * @child_setup: (scope async) (nullable): function to run in the child just before exec() - * @user_data: (closure): user data for @child_setup - * @child_pid: (out) (optional): return location for child process reference, or %NULL - * @error: return location for error - * - * Executes a child program asynchronously. - * - * See g_spawn_async_with_pipes() for a full description; this function - * simply calls the g_spawn_async_with_pipes() without any pipes. - * - * You should call g_spawn_close_pid() on the returned child process - * reference when you don't need it any more. - * - * If you are writing a GTK application, and the program you are spawning is a - * graphical application too, then to ensure that the spawned program opens its - * windows on the right screen, you may want to use #GdkAppLaunchContext, - * #GAppLaunchContext, or set the %DISPLAY environment variable. - * - * Note that the returned @child_pid on Windows is a handle to the child - * process and not its identifier. Process handles and process identifiers - * are different concepts on Windows. - * - * Returns: %TRUE on success, %FALSE if error is set - */ - - -/** - * g_spawn_async_with_fds: - * @working_directory: (type filename) (nullable): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding - * @argv: (array zero-terminated=1): child's argument vector, in the GLib file name encoding - * @envp: (array zero-terminated=1) (nullable): child's environment, or %NULL to inherit parent's, in the GLib file name encoding - * @flags: flags from #GSpawnFlags - * @child_setup: (scope async) (nullable): function to run in the child just before exec() - * @user_data: (closure): user data for @child_setup - * @child_pid: (out) (optional): return location for child process ID, or %NULL - * @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 error - * - * Executes a child program asynchronously. - * - * Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, - * so no FD assignments are used. - * - * Returns: %TRUE on success, %FALSE if an error was set - * Since: 2.58 - */ - - -/** - * g_spawn_async_with_pipes: - * @working_directory: (type filename) (nullable): child's current working - * directory, or %NULL to inherit parent's, in the GLib file name encoding - * @argv: (array zero-terminated=1) (element-type filename): child's argument - * vector, in the GLib file name encoding - * @envp: (array zero-terminated=1) (element-type filename) (nullable): - * child's environment, or %NULL to inherit parent's, in the GLib file - * name encoding - * @flags: flags from #GSpawnFlags - * @child_setup: (scope async) (nullable): function to run in the child just before exec() - * @user_data: (closure): user data for @child_setup - * @child_pid: (out) (optional): return location for child process ID, or %NULL - * @standard_input: (out) (optional): return location for file descriptor to write to child's stdin, or %NULL - * @standard_output: (out) (optional): return location for file descriptor to read child's stdout, or %NULL - * @standard_error: (out) (optional): return location for file descriptor to read child's stderr, or %NULL - * @error: return location for error - * - * Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, - * so no FD assignments are used. - * - * Returns: %TRUE on success, %FALSE if an error was set - */ - - -/** - * g_spawn_async_with_pipes_and_fds: - * @working_directory: (type filename) (nullable): child's current working - * directory, or %NULL to inherit parent's, in the GLib file name encoding - * @argv: (array zero-terminated=1) (element-type filename): child's argument - * vector, in the GLib file name encoding - * @envp: (array zero-terminated=1) (element-type filename) (nullable): - * child's environment, or %NULL to inherit parent's, in the GLib file - * name encoding - * @flags: flags from #GSpawnFlags - * @child_setup: (scope async) (nullable): function to run in the child just before `exec()` - * @user_data: (closure): user data for @child_setup - * @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` - * @source_fds: (array length=n_fds) (nullable): array of FDs from the parent - * process to make available in the child process - * @target_fds: (array length=n_fds) (nullable): array of FDs to remap - * @source_fds to in the child process - * @n_fds: number of FDs in @source_fds and @target_fds - * @child_pid_out: (out) (optional): return location for child process ID, or %NULL - * @stdin_pipe_out: (out) (optional): return location for file descriptor to write to child's stdin, or %NULL - * @stdout_pipe_out: (out) (optional): return location for file descriptor to read child's stdout, or %NULL - * @stderr_pipe_out: (out) (optional): return location for file descriptor to read child's stderr, or %NULL - * @error: return location for error - * - * Executes a child program asynchronously (your program will not - * block waiting for the child to exit). - * - * The child program is specified by the only argument that must be - * provided, @argv. @argv should be a %NULL-terminated array of strings, - * to be passed as the argument vector for the child. The first string - * in @argv is of course the name of the program to execute. By default, - * the name of the program must be a full path. If @flags contains the - * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is used to - * search for the executable. If @flags contains the - * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from @envp - * is used to search for the executable. If both the - * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags are - * set, the `PATH` variable from @envp takes precedence over the - * environment variable. - * - * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag - * is not used, then the program will be run from the current directory - * (or @working_directory, if specified); this might be unexpected or even - * dangerous in some cases when the current directory is world-writable. - * - * On Windows, note that all the string or string vector arguments to - * this function and the other `g_spawn*()` functions are in UTF-8, the - * GLib file name encoding. Unicode characters that are not part of - * the system codepage passed in these arguments will be correctly - * available in the spawned program only if it uses wide character API - * to retrieve its command line. For C programs built with Microsoft's - * tools it is enough to make the program have a `wmain()` instead of - * `main()`. `wmain()` has a wide character argument vector as parameter. - * - * At least currently, mingw doesn't support `wmain()`, so if you use - * mingw to develop the spawned program, it should call - * g_win32_get_command_line() to get arguments in UTF-8. - * - * On Windows the low-level child process creation API `CreateProcess()` - * doesn't use argument vectors, but a command line. The C runtime - * library's `spawn*()` family of functions (which g_spawn_async_with_pipes() - * eventually calls) paste the argument vector elements together into - * a command line, and the C runtime startup code does a corresponding - * reconstruction of an argument vector from the command line, to be - * passed to `main()`. Complications arise when you have argument vector - * elements that contain spaces or double quotes. The `spawn*()` functions - * don't do any quoting or escaping, but on the other hand the startup - * code does do unquoting and unescaping in order to enable receiving - * arguments with embedded spaces or double quotes. To work around this - * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on - * argument vector elements that need it before calling the C runtime - * `spawn()` function. - * - * The returned @child_pid on Windows is a handle to the child - * process, not its identifier. Process handles and process - * identifiers are different concepts on Windows. - * - * @envp is a %NULL-terminated array of strings, where each string - * has the form `KEY=VALUE`. This will become the child's environment. - * If @envp is %NULL, the child inherits its parent's environment. - * - * @flags should be the bitwise OR of any flags you want to affect the - * function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the - * child will not automatically be reaped; you must use a child watch - * (g_child_watch_add()) to be notified about the death of the child process, - * otherwise it will stay around as a zombie process until this process exits. - * Eventually you must call g_spawn_close_pid() on the @child_pid, in order to - * free resources which may be associated with the child process. (On Unix, - * using a child watch is equivalent to calling waitpid() or handling - * the `SIGCHLD` signal manually. On Windows, calling g_spawn_close_pid() - * is equivalent to calling `CloseHandle()` on the process handle returned - * in @child_pid). See g_child_watch_add(). - * - * Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically - * closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that - * other open file descriptors will be inherited by the child; otherwise all - * descriptors except stdin/stdout/stderr will be closed before calling `exec()` - * in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an - * absolute path, it will be looked for in the `PATH` environment - * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an - * absolute path, it will be looked for in the `PATH` variable from - * @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP - * are used, the value from @envp takes precedence over the environment. - * - * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output - * will be discarded, instead of going to the same location as the parent's - * standard output. If you use this flag, @stdout_pipe_out must be %NULL. - * - * %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error - * will be discarded, instead of going to the same location as the parent's - * standard error. If you use this flag, @stderr_pipe_out must be %NULL. - * - * %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's - * standard input (by default, the child's standard input is attached to - * `/dev/null`). If you use this flag, @stdin_pipe_out must be %NULL. - * - * It is valid to pass the same FD in multiple parameters (e.g. you can pass - * a single FD for both @stdout_fd and @stderr_fd, and include it in - * @source_fds too). - * - * @source_fds and @target_fds allow zero or more FDs from this process to be - * remapped to different FDs in the spawned process. If @n_fds is greater than - * zero, @source_fds and @target_fds must both be non-%NULL and the same length. - * Each FD in @source_fds is remapped to the FD number at the same index in - * @target_fds. The source and target FD may be equal to simply propagate an FD - * to the spawned process. FD remappings are processed after standard FDs, so - * any target FDs which equal @stdin_fd, @stdout_fd or @stderr_fd will overwrite - * them in the spawned process. - * - * %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is - * the file to execute, while the remaining elements are the actual - * argument vector to pass to the file. Normally g_spawn_async_with_pipes() - * uses @argv[0] as the file to execute, and passes all of @argv to the child. - * - * @child_setup and @user_data are a function and user data. On POSIX - * platforms, the function is called in the child after GLib has - * performed all the setup it plans to perform (including creating - * pipes, closing file descriptors, etc.) but before calling `exec()`. - * That is, @child_setup is called just before calling `exec()` in the - * child. Obviously actions taken in this function will only affect - * the child, not the parent. - * - * On Windows, there is no separate `fork()` and `exec()` functionality. - * Child processes are created and run with a single API call, - * `CreateProcess()`. There is no sensible thing @child_setup - * could be used for on Windows so it is ignored and not called. - * - * If non-%NULL, @child_pid will on Unix be filled with the child's - * process ID. You can use the process ID to send signals to the child, - * or to use g_child_watch_add() (or `waitpid()`) if you specified the - * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be - * filled with a handle to the child process only if you specified the - * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child - * process using the Win32 API, for example wait for its termination - * with the `WaitFor*()` functions, or examine its exit code with - * `GetExitCodeProcess()`. You should close the handle with `CloseHandle()` - * or g_spawn_close_pid() when you no longer need it. - * - * If non-%NULL, the @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out - * locations will be filled with file descriptors for writing to the child's - * standard input or reading from its standard output or standard error. - * The caller of g_spawn_async_with_pipes() must close these file descriptors - * when they are no longer in use. If these parameters are %NULL, the - * corresponding pipe won't be created. - * - * If @stdin_pipe_out is %NULL, the child's standard input is attached to - * `/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set. - * - * If @stderr_pipe_out is NULL, the child's standard error goes to the same - * location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL - * is set. - * - * If @stdout_pipe_out is NULL, the child's standard output goes to the same - * location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL - * is set. - * - * @error can be %NULL to ignore errors, or non-%NULL to report errors. - * If an error is set, the function returns %FALSE. Errors are reported - * even if they occur in the child (for example if the executable in - * `@argv[0]` is not found). Typically the `message` field of returned - * errors should be displayed to users. Possible errors are those from - * the #G_SPAWN_ERROR domain. - * - * If an error occurs, @child_pid, @stdin_pipe_out, @stdout_pipe_out, - * and @stderr_pipe_out will not be filled with valid values. - * - * If @child_pid is not %NULL and an error does not occur then the returned - * process reference must be closed using g_spawn_close_pid(). - * - * On modern UNIX platforms, GLib can use an efficient process launching - * codepath driven internally by `posix_spawn()`. This has the advantage of - * avoiding the fork-time performance costs of cloning the parent process - * address space, and avoiding associated memory overcommit checks that are - * not relevant in the context of immediately executing a distinct process. - * This optimized codepath will be used provided that the following conditions - * are met: - * - * 1. %G_SPAWN_DO_NOT_REAP_CHILD is set - * 2. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN is set - * 3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set - * 4. @working_directory is %NULL - * 5. @child_setup is %NULL - * 6. The program is of a recognised binary format, or has a shebang. - * Otherwise, GLib will have to execute the program through the - * shell, which is not done using the optimized codepath. - * - * If you are writing a GTK application, and the program you are spawning is a - * graphical application too, then to ensure that the spawned program opens its - * windows on the right screen, you may want to use #GdkAppLaunchContext, - * #GAppLaunchContext, or set the `DISPLAY` environment variable. - * - * Returns: %TRUE on success, %FALSE if an error was set - * Since: 2.68 - */ - - -/** - * g_spawn_check_exit_status: - * @wait_status: A status as returned from g_spawn_sync() - * @error: a #GError - * - * An old name for g_spawn_check_wait_status(), deprecated because its - * name is misleading. - * - * Despite the name of the function, @wait_status must be the wait status - * as returned by g_spawn_sync(), g_subprocess_get_status(), `waitpid()`, - * etc. On Unix platforms, it is incorrect for it to be the exit status - * as passed to `exit()` or returned by g_subprocess_get_exit_status() or - * `WEXITSTATUS()`. - * - * Returns: %TRUE if child exited successfully, %FALSE otherwise (and - * @error will be set) - * Since: 2.34 - * Deprecated: 2.70: Use g_spawn_check_wait_status() instead, and check whether your code is conflating wait and exit statuses. - */ - - -/** - * g_spawn_check_wait_status: - * @wait_status: A platform-specific wait status as returned from g_spawn_sync() - * @error: a #GError - * - * Set @error if @wait_status indicates the child exited abnormally - * (e.g. with a nonzero exit code, or via a fatal signal). - * - * The g_spawn_sync() and g_child_watch_add() family of APIs return the - * status of subprocesses encoded in a platform-specific way. - * On Unix, this is guaranteed to be in the same format waitpid() returns, - * and on Windows it is guaranteed to be the result of GetExitCodeProcess(). - * - * Prior to the introduction of this function in GLib 2.34, interpreting - * @wait_status required use of platform-specific APIs, which is problematic - * for software using GLib as a cross-platform layer. - * - * Additionally, many programs simply want to determine whether or not - * the child exited successfully, and either propagate a #GError or - * print a message to standard error. In that common case, this function - * can be used. Note that the error message in @error will contain - * human-readable information about the wait status. - * - * The @domain and @code of @error have special semantics in the case - * where the process has an "exit code", as opposed to being killed by - * a signal. On Unix, this happens if WIFEXITED() would be true of - * @wait_status. On Windows, it is always the case. - * - * The special semantics are that the actual exit code will be the - * code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR. - * This allows you to differentiate between different exit codes. - * - * If the process was terminated by some means other than an exit - * status (for example if it was killed by a signal), the domain will be - * %G_SPAWN_ERROR and the code will be %G_SPAWN_ERROR_FAILED. - * - * This function just offers convenience; you can of course also check - * the available platform via a macro such as %G_OS_UNIX, and use - * WIFEXITED() and WEXITSTATUS() on @wait_status directly. Do not attempt - * to scan or parse the error message string; it may be translated and/or - * change in future versions of GLib. - * - * Prior to version 2.70, g_spawn_check_exit_status() provides the same - * functionality, although under a misleading name. - * - * Returns: %TRUE if child exited successfully, %FALSE otherwise (and - * @error will be set) - * Since: 2.70 - */ - - -/** - * g_spawn_close_pid: - * @pid: The process reference to close - * - * On some platforms, notably Windows, the #GPid type represents a resource - * which must be closed to prevent resource leaking. g_spawn_close_pid() - * is provided for this purpose. It should be used on all platforms, even - * though it doesn't do anything under UNIX. - */ - - -/** - * g_spawn_command_line_async: - * @command_line: (type filename): a command line - * @error: return location for errors - * - * A simple version of g_spawn_async() that parses a command line with - * g_shell_parse_argv() and passes it to g_spawn_async(). - * - * Runs a command line in the background. Unlike g_spawn_async(), the - * %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note - * that %G_SPAWN_SEARCH_PATH can have security implications, so - * consider using g_spawn_async() directly if appropriate. Possible - * errors are those from g_shell_parse_argv() and g_spawn_async(). - * - * The same concerns on Windows apply as for g_spawn_command_line_sync(). - * - * Returns: %TRUE on success, %FALSE if error is set - */ - - -/** - * g_spawn_command_line_sync: - * @command_line: (type filename): a command line - * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output - * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child errors - * @wait_status: (out) (optional): return location for child wait status, as returned by waitpid() - * @error: return location for errors - * - * A simple version of g_spawn_sync() with little-used parameters - * removed, taking a command line instead of an argument vector. - * - * See g_spawn_sync() for full details. - * - * The @command_line argument will be parsed by g_shell_parse_argv(). - * - * Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled. - * Note that %G_SPAWN_SEARCH_PATH can have security implications, so - * consider using g_spawn_sync() directly if appropriate. - * - * Possible errors are those from g_spawn_sync() and those - * from g_shell_parse_argv(). - * - * If @wait_status is non-%NULL, the platform-specific status of - * the child is stored there; see the documentation of - * g_spawn_check_wait_status() for how to use and interpret this. - * On Unix platforms, note that it is usually not equal - * to the integer passed to `exit()` or returned from `main()`. - * - * On Windows, please note the implications of g_shell_parse_argv() - * parsing @command_line. Parsing is done according to Unix shell rules, not - * Windows command interpreter rules. - * Space is a separator, and backslashes are - * special. Thus you cannot simply pass a @command_line containing - * canonical Windows paths, like "c:\\program files\\app\\app.exe", as - * the backslashes will be eaten, and the space will act as a - * separator. You need to enclose such paths with single quotes, like - * "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'". - * - * Returns: %TRUE on success, %FALSE if an error was set - */ - - -/** - * g_spawn_sync: - * @working_directory: (type filename) (nullable): child's current working - * directory, or %NULL to inherit parent's - * @argv: (array zero-terminated=1) (element-type filename): - * child's argument vector - * @envp: (array zero-terminated=1) (element-type filename) (nullable): - * child's environment, or %NULL to inherit parent's - * @flags: flags from #GSpawnFlags - * @child_setup: (scope async) (nullable): function to run in the child just before exec() - * @user_data: (closure): user data for @child_setup - * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output, or %NULL - * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child error messages, or %NULL - * @wait_status: (out) (optional): return location for child wait status, as returned by waitpid(), or %NULL - * @error: return location for error, or %NULL - * - * Executes a child synchronously (waits for the child to exit before returning). - * - * All output from the child is stored in @standard_output and @standard_error, - * if those parameters are non-%NULL. Note that you must set the - * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when - * passing %NULL for @standard_output and @standard_error. - * - * If @wait_status is non-%NULL, the platform-specific status of - * the child is stored there; see the documentation of - * g_spawn_check_wait_status() for how to use and interpret this. - * On Unix platforms, note that it is usually not equal - * to the integer passed to `exit()` or returned from `main()`. - * - * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in - * @flags, and on POSIX platforms, the same restrictions as for - * g_child_watch_source_new() apply. - * - * If an error occurs, no data is returned in @standard_output, - * @standard_error, or @wait_status. - * - * This function calls g_spawn_async_with_pipes() internally; see that - * function for full details on the other parameters and details on - * how these functions work on Windows. - * - * Returns: %TRUE on success, %FALSE if an error was set - */ - - -/** - * g_sprintf: - * @string: A pointer to a memory buffer to contain the resulting string. It - * is up to the caller to ensure that the allocated buffer is large - * enough to hold the formatted result - * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] - * @...: the arguments to insert in the output. - * - * An implementation of the standard sprintf() function which supports - * positional parameters, as specified in the Single Unix Specification. - * - * Note that it is usually better to use g_snprintf(), to avoid the - * risk of buffer overflow. - * - * `glib/gprintf.h` must be explicitly included in order to use this function. - * - * See also g_strdup_printf(). - * - * Returns: the number of bytes printed. - * Since: 2.2 - */ - - -/** - * g_stat: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * @buf: a pointer to a stat struct, which will be filled with the file - * information - * - * A wrapper for the POSIX stat() function. The stat() function - * returns information about a file. On Windows the stat() function in - * the C library checks only the FAT-style READONLY attribute and does - * not look at the ACL at all. Thus on Windows the protection bits in - * the @st_mode field are a fabrication of little use. - * - * On Windows the Microsoft C libraries have several variants of the - * stat struct and stat() function with names like _stat(), _stat32(), - * _stat32i64() and _stat64i32(). The one used here is for 32-bit code - * the one with 32-bit size and time fields, specifically called _stat32(). - * - * In Microsoft's compiler, by default struct stat means one with - * 64-bit time fields while in MinGW struct stat is the legacy one - * with 32-bit fields. To hopefully clear up this messs, the gstdio.h - * header defines a type #GStatBuf which is the appropriate struct type - * depending on the platform and/or compiler being used. On POSIX it - * is just struct stat, but note that even on POSIX platforms, stat() - * might be a macro. - * - * See your C library manual for more details about stat(). - * - * Returns: 0 if the information was successfully retrieved, - * -1 if an error occurred - * Since: 2.6 - */ - - -/** - * g_steal_fd: - * @fd_ptr: (not optional) (inout): A pointer to a file descriptor - * - * Sets @fd_ptr to `-1`, returning the value that was there before. - * - * Conceptually, this transfers the ownership of the file descriptor - * from the referenced variable to the caller of the function (i.e. - * ‘steals’ the reference). This is very similar to g_steal_pointer(), - * but for file descriptors. - * - * On POSIX platforms, this function is async-signal safe - * (see [`signal(7)`](man:signal(7)) and - * [`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a - * signal handler or a #GSpawnChildSetupFunc. - * - * Returns: the value that @fd_ptr previously had - * Since: 2.70 - */ - - -/** - * g_stpcpy: - * @dest: destination buffer. - * @src: source string. - * - * Copies a nul-terminated string into the dest buffer, include the - * trailing nul, and return a pointer to the trailing nul byte. - * This is useful for concatenating multiple strings together - * without having to repeatedly scan for the end. - * - * Returns: a pointer to trailing nul byte. - */ - - -/** - * g_str_equal: - * @v1: (not nullable): a key - * @v2: (not nullable): a key to compare with @v1 - * - * Compares two strings for byte-by-byte equality and returns %TRUE - * if they are equal. It can be passed to g_hash_table_new() as the - * @key_equal_func parameter, when using non-%NULL strings as keys in a - * #GHashTable. - * - * This function is typically used for hash table comparisons, but can be used - * for general purpose comparisons of non-%NULL strings. For a %NULL-safe string - * comparison function, see g_strcmp0(). - * - * Returns: %TRUE if the two keys match - */ - - -/** - * g_str_has_prefix: - * @str: a nul-terminated string - * @prefix: the nul-terminated prefix to look for - * - * Looks whether the string @str begins with @prefix. - * - * Returns: %TRUE if @str begins with @prefix, %FALSE otherwise. - * Since: 2.2 - */ - - -/** - * g_str_has_suffix: - * @str: a nul-terminated string - * @suffix: the nul-terminated suffix to look for - * - * Looks whether the string @str ends with @suffix. - * - * Returns: %TRUE if @str end with @suffix, %FALSE otherwise. - * Since: 2.2 - */ - - -/** - * g_str_hash: - * @v: (not nullable): a string key - * - * Converts a string to a hash value. - * - * This function implements the widely used "djb" hash apparently - * posted by Daniel Bernstein to comp.lang.c some time ago. The 32 - * bit unsigned hash value starts at 5381 and for each byte 'c' in - * the string, is updated: `hash = hash * 33 + c`. This function - * uses the signed value of each byte. - * - * It can be passed to g_hash_table_new() as the @hash_func parameter, - * when using non-%NULL strings as keys in a #GHashTable. - * - * Note that this function may not be a perfect fit for all use cases. - * For example, it produces some hash collisions with strings as short - * as 2. - * - * Returns: a hash value corresponding to the key - */ - - -/** - * g_str_is_ascii: - * @str: a string - * - * Determines if a string is pure ASCII. A string is pure ASCII if it - * contains no bytes with the high bit set. - * - * Returns: %TRUE if @str is ASCII - * Since: 2.40 - */ - - -/** - * g_str_match_string: - * @search_term: the search term from the user - * @potential_hit: the text that may be a hit - * @accept_alternates: %TRUE to accept ASCII alternates - * - * Checks if a search conducted for @search_term should match - * @potential_hit. - * - * This function calls g_str_tokenize_and_fold() on both - * @search_term and @potential_hit. ASCII alternates are never taken - * for @search_term but will be taken for @potential_hit according to - * the value of @accept_alternates. - * - * A hit occurs when each folded token in @search_term is a prefix of a - * folded token from @potential_hit. - * - * Depending on how you're performing the search, it will typically be - * faster to call g_str_tokenize_and_fold() on each string in - * your corpus and build an index on the returned folded tokens, then - * call g_str_tokenize_and_fold() on the search term and - * perform lookups into that index. - * - * As some examples, searching for ‘fred’ would match the potential hit - * ‘Smith, Fred’ and also ‘Frédéric’. Searching for ‘Fréd’ would match - * ‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of - * accent matching). Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo - * Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix). - * - * Returns: %TRUE if @potential_hit is a hit - * Since: 2.40 - */ - - -/** - * g_str_to_ascii: - * @str: a string, in UTF-8 - * @from_locale: (nullable): the source locale, if known - * - * Transliterate @str to plain ASCII. - * - * For best results, @str should be in composed normalised form. - * - * This function performs a reasonably good set of character - * replacements. The particular set of replacements that is done may - * change by version or even by runtime environment. - * - * If the source language of @str is known, it can used to improve the - * accuracy of the translation by passing it as @from_locale. It should - * be a valid POSIX locale string (of the form - * `language[_territory][.codeset][@modifier]`). - * - * If @from_locale is %NULL then the current locale is used. - * - * If you want to do translation for no specific locale, and you want it - * to be done independently of the currently locale, specify `"C"` for - * @from_locale. - * - * Returns: a string in plain ASCII - * Since: 2.40 - */ - - -/** - * g_str_tokenize_and_fold: - * @string: a string - * @translit_locale: (nullable): the language code (like 'de' or - * 'en_GB') from which @string originates - * @ascii_alternates: (out) (transfer full) (array zero-terminated=1): a - * return location for ASCII alternates - * - * Tokenises @string and performs folding on each token. - * - * A token is a non-empty sequence of alphanumeric characters in the - * source string, separated by non-alphanumeric characters. An - * "alphanumeric" character for this purpose is one that matches - * g_unichar_isalnum() or g_unichar_ismark(). - * - * Each token is then (Unicode) normalised and case-folded. If - * @ascii_alternates is non-%NULL and some of the returned tokens - * contain non-ASCII characters, ASCII alternatives will be generated. - * - * The number of ASCII alternatives that are generated and the method - * for doing so is unspecified, but @translit_locale (if specified) may - * improve the transliteration if the language of the source string is - * known. - * - * Returns: (transfer full) (array zero-terminated=1): the folded tokens - * Since: 2.40 - */ - - -/** - * g_strcanon: - * @string: a nul-terminated array of bytes - * @valid_chars: bytes permitted in @string - * @substitutor: replacement character for disallowed bytes - * - * For each character in @string, if the character is not in @valid_chars, - * replaces the character with @substitutor. - * - * Modifies @string in place, and return @string itself, not a copy. The - * return value is to allow nesting such as: - * - * |[<!-- language="C" --> - * g_ascii_strup (g_strcanon (str, "abc", '?')) - * ]| - * - * In order to modify a copy, you may use g_strdup(): - * - * |[<!-- language="C" --> - * reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); - * ... - * g_free (reformatted); - * ]| - * - * Returns: the modified @string - */ - - -/** - * g_strcasecmp: - * @s1: a string - * @s2: a string to compare with @s1 - * - * A case-insensitive string comparison, corresponding to the standard - * strcasecmp() function on platforms which support it. - * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. - * Deprecated: 2.2: See g_strncasecmp() for a discussion of why this - * function is deprecated and how to replace it. - */ - - -/** - * g_strchomp: - * @string: a string to remove the trailing whitespace from - * - * Removes trailing whitespace from a string. - * - * This function doesn't allocate or reallocate any memory; - * it modifies @string in place. Therefore, it cannot be used - * on statically allocated strings. - * - * The pointer to @string is returned to allow the nesting of functions. - * - * Also see g_strchug() and g_strstrip(). - * - * Returns: @string - */ - - -/** - * g_strchug: - * @string: a string to remove the leading whitespace from - * - * Removes leading whitespace from a string, by moving the rest - * of the characters forward. - * - * This function doesn't allocate or reallocate any memory; - * it modifies @string in place. Therefore, it cannot be used on - * statically allocated strings. - * - * The pointer to @string is returned to allow the nesting of functions. - * - * Also see g_strchomp() and g_strstrip(). - * - * Returns: @string - */ - - -/** - * g_strcmp0: - * @str1: (nullable): a C string or %NULL - * @str2: (nullable): another C string or %NULL - * - * Compares @str1 and @str2 like strcmp(). Handles %NULL - * gracefully by sorting it before non-%NULL strings. - * Comparing two %NULL pointers returns 0. - * - * Returns: an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2. - * Since: 2.16 - */ - - -/** - * g_strcompress: - * @source: a string to compress - * - * Replaces all escaped characters with their one byte equivalent. - * - * This function does the reverse conversion of g_strescape(). - * - * Returns: a newly-allocated copy of @source with all escaped - * character compressed - */ - - -/** - * g_strconcat: - * @string1: the first string to add, which must not be %NULL - * @...: a %NULL-terminated list of strings to append to the string - * - * Concatenates all of the given strings into one long string. The - * returned string should be freed with g_free() when no longer needed. - * - * The variable argument list must end with %NULL. If you forget the %NULL, - * g_strconcat() will start appending random memory junk to your string. - * - * Note that this function is usually not the right function to use to - * assemble a translated message from pieces, since proper translation - * often requires the pieces to be reordered. - * - * Returns: a newly-allocated string containing all the string arguments - */ - - -/** - * g_strdelimit: - * @string: the string to convert - * @delimiters: (nullable): a string containing the current delimiters, - * or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS - * @new_delimiter: the new delimiter character - * - * Converts any delimiter characters in @string to @new_delimiter. - * - * Any characters in @string which are found in @delimiters are - * changed to the @new_delimiter character. Modifies @string in place, - * and returns @string itself, not a copy. - * - * The return value is to allow nesting such as: - * - * |[<!-- language="C" --> - * g_ascii_strup (g_strdelimit (str, "abc", '?')) - * ]| - * - * In order to modify a copy, you may use g_strdup(): - * - * |[<!-- language="C" --> - * reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); - * ... - * g_free (reformatted); - * ]| - * - * Returns: the modified @string - */ - - -/** - * g_strdown: - * @string: the string to convert. - * - * Converts a string to lower case. - * - * Returns: the string - * Deprecated: 2.2: This function is totally broken for the reasons discussed - * in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() - * instead. - */ - - -/** - * g_strdup: - * @str: (nullable): the string to duplicate - * - * Duplicates a string. If @str is %NULL it returns %NULL. - * The returned string should be freed with g_free() - * when no longer needed. - * - * Returns: a newly-allocated copy of @str - */ - - -/** - * g_strdup_printf: - * @format: (not nullable): a standard printf() format string, but notice - * [string precision pitfalls][string-precision] - * @...: the parameters to insert into the format string - * - * Similar to the standard C sprintf() function but safer, since it - * calculates the maximum space required and allocates memory to hold - * the result. The returned string should be freed with g_free() when no - * longer needed. - * - * The returned string is guaranteed to be non-NULL, unless @format - * contains `%lc` or `%ls` conversions, which can fail if no multibyte - * representation is available for the given character. - * - * Returns: a newly-allocated string holding the result - */ - - -/** - * g_strdup_vprintf: - * @format: (not nullable): a standard printf() format string, but notice - * [string precision pitfalls][string-precision] - * @args: the list of parameters to insert into the format string - * - * Similar to the standard C vsprintf() function but safer, since it - * calculates the maximum space required and allocates memory to hold - * the result. The returned string should be freed with g_free() when - * no longer needed. - * - * The returned string is guaranteed to be non-NULL, unless @format - * contains `%lc` or `%ls` conversions, which can fail if no multibyte - * representation is available for the given character. - * - * See also g_vasprintf(), which offers the same functionality, but - * additionally returns the length of the allocated string. - * - * Returns: a newly-allocated string holding the result - */ - - -/** - * g_strdupv: - * @str_array: (nullable): a %NULL-terminated array of strings - * - * Copies %NULL-terminated array of strings. The copy is a deep copy; - * the new array should be freed by first freeing each string, then - * the array itself. g_strfreev() does this for you. If called - * on a %NULL value, g_strdupv() simply returns %NULL. - * - * Returns: (nullable): a new %NULL-terminated array of strings. - */ - - -/** - * g_strerror: - * @errnum: the system error number. See the standard C %errno - * documentation - * - * Returns a string corresponding to the given error code, e.g. "no - * such process". Unlike strerror(), this always returns a string in - * UTF-8 encoding, and the pointer is guaranteed to remain valid for - * the lifetime of the process. - * - * Note that the string may be translated according to the current locale. - * - * The value of %errno will not be changed by this function. However, it may - * be changed by intermediate function calls, so you should save its value - * as soon as the call returns: - * |[ - * int saved_errno; - * - * ret = read (blah); - * saved_errno = errno; - * - * g_strerror (saved_errno); - * ]| - * - * Returns: a UTF-8 string describing the error code. If the error code - * is unknown, it returns a string like "unknown error (<code>)". - */ - - -/** - * g_strescape: - * @source: a string to escape - * @exceptions: (nullable): a string of characters not to escape in @source - * - * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\' - * and '"' in the string @source by inserting a '\' before - * them. Additionally all characters in the range 0x01-0x1F (everything - * below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are - * replaced with a '\' followed by their octal representation. - * Characters supplied in @exceptions are not escaped. - * - * g_strcompress() does the reverse conversion. - * - * Returns: a newly-allocated copy of @source with certain - * characters escaped. See above. - */ - - -/** - * g_strfreev: - * @str_array: (nullable): a %NULL-terminated array of strings to free - * - * Frees a %NULL-terminated array of strings, as well as each - * string it contains. - * - * If @str_array is %NULL, this function simply returns. - */ - - -/** - * g_string_append: - * @string: a #GString - * @val: the string to append onto the end of @string - * - * Adds a string onto the end of a #GString, expanding - * it if necessary. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_append_c: - * @string: a #GString - * @c: the byte to append onto the end of @string - * - * Adds a byte onto the end of a #GString, expanding - * it if necessary. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_append_len: - * @string: a #GString - * @val: bytes to append - * @len: number of bytes of @val to use, or -1 for all of @val - * - * Appends @len bytes of @val to @string. - * - * If @len is positive, @val may contain embedded nuls and need - * not be nul-terminated. It is the caller's responsibility to - * ensure that @val has at least @len addressable bytes. - * - * If @len is negative, @val must be nul-terminated and @len - * is considered to request the entire string length. This - * makes g_string_append_len() equivalent to g_string_append(). - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_append_printf: - * @string: a #GString - * @format: the string format. See the printf() documentation - * @...: the parameters to insert into the format string - * - * Appends a formatted string onto the end of a #GString. - * This function is similar to g_string_printf() except - * that the text is appended to the #GString. - */ - - -/** - * g_string_append_unichar: - * @string: a #GString - * @wc: a Unicode character - * - * Converts a Unicode character into UTF-8, and appends it - * to the string. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_append_uri_escaped: - * @string: a #GString - * @unescaped: a string - * @reserved_chars_allowed: a string of reserved characters allowed - * to be used, or %NULL - * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters - * - * Appends @unescaped to @string, escaping any characters that - * are reserved in URIs using URI-style escape sequences. - * - * Returns: (transfer none): @string - * Since: 2.16 - */ - - -/** - * g_string_append_vprintf: - * @string: a #GString - * @format: (not nullable): the string format. See the printf() documentation - * @args: the list of arguments to insert in the output - * - * Appends a formatted string onto the end of a #GString. - * This function is similar to g_string_append_printf() - * except that the arguments to the format string are passed - * as a va_list. - * - * Since: 2.14 - */ - - -/** - * g_string_ascii_down: - * @string: a GString - * - * Converts all uppercase ASCII letters to lowercase ASCII letters. - * - * Returns: (transfer none): passed-in @string pointer, with all the - * uppercase characters converted to lowercase in place, - * with semantics that exactly match g_ascii_tolower(). - */ - - -/** - * g_string_ascii_up: - * @string: a GString - * - * Converts all lowercase ASCII letters to uppercase ASCII letters. - * - * Returns: (transfer none): passed-in @string pointer, with all the - * lowercase characters converted to uppercase in place, - * with semantics that exactly match g_ascii_toupper(). - */ - - -/** - * g_string_assign: - * @string: the destination #GString. Its current contents - * are destroyed. - * @rval: the string to copy into @string - * - * Copies the bytes from a string into a #GString, - * destroying any previous contents. It is rather like - * the standard strcpy() function, except that you do not - * have to worry about having enough space to copy the string. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_chunk_clear: - * @chunk: a #GStringChunk - * - * Frees all strings contained within the #GStringChunk. - * After calling g_string_chunk_clear() it is not safe to - * access any of the strings which were contained within it. - * - * Since: 2.14 - */ - - -/** - * g_string_chunk_free: - * @chunk: a #GStringChunk - * - * Frees all memory allocated by the #GStringChunk. - * After calling g_string_chunk_free() it is not safe to - * access any of the strings which were contained within it. - */ - - -/** - * g_string_chunk_insert: - * @chunk: a #GStringChunk - * @string: the string to add - * - * Adds a copy of @string to the #GStringChunk. - * It returns a pointer to the new copy of the string - * in the #GStringChunk. The characters in the string - * can be changed, if necessary, though you should not - * change anything after the end of the string. - * - * Unlike g_string_chunk_insert_const(), this function - * does not check for duplicates. Also strings added - * with g_string_chunk_insert() will not be searched - * by g_string_chunk_insert_const() when looking for - * duplicates. - * - * Returns: a pointer to the copy of @string within - * the #GStringChunk - */ - - -/** - * g_string_chunk_insert_const: - * @chunk: a #GStringChunk - * @string: the string to add - * - * Adds a copy of @string to the #GStringChunk, unless the same - * string has already been added to the #GStringChunk with - * g_string_chunk_insert_const(). - * - * This function is useful if you need to copy a large number - * of strings but do not want to waste space storing duplicates. - * But you must remember that there may be several pointers to - * the same string, and so any changes made to the strings - * should be done very carefully. - * - * Note that g_string_chunk_insert_const() will not return a - * pointer to a string added with g_string_chunk_insert(), even - * if they do match. - * - * Returns: a pointer to the new or existing copy of @string - * within the #GStringChunk - */ - - -/** - * g_string_chunk_insert_len: - * @chunk: a #GStringChunk - * @string: bytes to insert - * @len: number of bytes of @string to insert, or -1 to insert a - * nul-terminated string - * - * Adds a copy of the first @len bytes of @string to the #GStringChunk. - * The copy is nul-terminated. - * - * Since this function does not stop at nul bytes, it is the caller's - * responsibility to ensure that @string has at least @len addressable - * bytes. - * - * The characters in the returned string can be changed, if necessary, - * though you should not change anything after the end of the string. - * - * Returns: a pointer to the copy of @string within the #GStringChunk - * Since: 2.4 - */ - - -/** - * g_string_chunk_new: - * @size: the default size of the blocks of memory which are - * allocated to store the strings. If a particular string - * is larger than this default size, a larger block of - * memory will be allocated for it. - * - * Creates a new #GStringChunk. - * - * Returns: a new #GStringChunk - */ - - -/** - * g_string_down: - * @string: a #GString - * - * Converts a #GString to lowercase. - * - * Returns: (transfer none): the #GString - * Deprecated: 2.2: This function uses the locale-specific - * tolower() function, which is almost never the right thing. - * Use g_string_ascii_down() or g_utf8_strdown() instead. - */ - - -/** - * g_string_equal: - * @v: a #GString - * @v2: another #GString - * - * Compares two strings for equality, returning %TRUE if they are equal. - * For use with #GHashTable. - * - * Returns: %TRUE if the strings are the same length and contain the - * same bytes - */ - - -/** - * g_string_erase: - * @string: a #GString - * @pos: the position of the content to remove - * @len: the number of bytes to remove, or -1 to remove all - * following bytes - * - * Removes @len bytes from a #GString, starting at position @pos. - * The rest of the #GString is shifted down to fill the gap. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_free: - * @string: (transfer full): a #GString - * @free_segment: if %TRUE, the actual character data is freed as well - * - * Frees the memory allocated for the #GString. - * If @free_segment is %TRUE it also frees the character data. If - * it's %FALSE, the caller gains ownership of the buffer and must - * free it after use with g_free(). - * - * Returns: (nullable): the character data of @string - * (i.e. %NULL if @free_segment is %TRUE) - */ - - -/** - * g_string_free_to_bytes: - * @string: (transfer full): a #GString - * - * Transfers ownership of the contents of @string to a newly allocated - * #GBytes. The #GString structure itself is deallocated, and it is - * therefore invalid to use @string after invoking this function. - * - * Note that while #GString ensures that its buffer always has a - * trailing nul character (not reflected in its "len"), the returned - * #GBytes does not include this extra nul; i.e. it has length exactly - * equal to the "len" member. - * - * Returns: (transfer full): A newly allocated #GBytes containing contents of @string; @string itself is freed - * Since: 2.34 - */ - - -/** - * g_string_hash: - * @str: a string to hash - * - * Creates a hash code for @str; for use with #GHashTable. - * - * Returns: hash code for @str - */ - - -/** - * g_string_insert: - * @string: a #GString - * @pos: the position to insert the copy of the string - * @val: the string to insert - * - * Inserts a copy of a string into a #GString, - * expanding it if necessary. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_insert_c: - * @string: a #GString - * @pos: the position to insert the byte - * @c: the byte to insert - * - * Inserts a byte into a #GString, expanding it if necessary. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_insert_len: - * @string: a #GString - * @pos: position in @string where insertion should - * happen, or -1 for at the end - * @val: bytes to insert - * @len: number of bytes of @val to insert, or -1 for all of @val - * - * Inserts @len bytes of @val into @string at @pos. - * - * If @len is positive, @val may contain embedded nuls and need - * not be nul-terminated. It is the caller's responsibility to - * ensure that @val has at least @len addressable bytes. - * - * If @len is negative, @val must be nul-terminated and @len - * is considered to request the entire string length. - * - * If @pos is -1, bytes are inserted at the end of the string. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_insert_unichar: - * @string: a #GString - * @pos: the position at which to insert character, or -1 - * to append at the end of the string - * @wc: a Unicode character - * - * Converts a Unicode character into UTF-8, and insert it - * into the string at the given position. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_new: (constructor) - * @init: (nullable): the initial text to copy into the string, or %NULL to - * start with an empty string - * - * Creates a new #GString, initialized with the given string. - * - * Returns: (transfer full): the new #GString - */ - - -/** - * g_string_new_len: (constructor) - * @init: initial contents of the string - * @len: length of @init to use - * - * Creates a new #GString with @len bytes of the @init buffer. - * Because a length is provided, @init need not be nul-terminated, - * and can contain embedded nul bytes. - * - * Since this function does not stop at nul bytes, it is the caller's - * responsibility to ensure that @init has at least @len addressable - * bytes. - * - * Returns: (transfer full): a new #GString - */ - - -/** - * g_string_overwrite: - * @string: a #GString - * @pos: the position at which to start overwriting - * @val: the string that will overwrite the @string starting at @pos - * - * Overwrites part of a string, lengthening it if necessary. - * - * Returns: (transfer none): @string - * Since: 2.14 - */ - - -/** - * g_string_overwrite_len: - * @string: a #GString - * @pos: the position at which to start overwriting - * @val: the string that will overwrite the @string starting at @pos - * @len: the number of bytes to write from @val - * - * Overwrites part of a string, lengthening it if necessary. - * This function will work with embedded nuls. - * - * Returns: (transfer none): @string - * Since: 2.14 - */ - - -/** - * g_string_prepend: - * @string: a #GString - * @val: the string to prepend on the start of @string - * - * Adds a string on to the start of a #GString, - * expanding it if necessary. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_prepend_c: - * @string: a #GString - * @c: the byte to prepend on the start of the #GString - * - * Adds a byte onto the start of a #GString, - * expanding it if necessary. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_prepend_len: - * @string: a #GString - * @val: bytes to prepend - * @len: number of bytes in @val to prepend, or -1 for all of @val - * - * Prepends @len bytes of @val to @string. - * - * If @len is positive, @val may contain embedded nuls and need - * not be nul-terminated. It is the caller's responsibility to - * ensure that @val has at least @len addressable bytes. - * - * If @len is negative, @val must be nul-terminated and @len - * is considered to request the entire string length. This - * makes g_string_prepend_len() equivalent to g_string_prepend(). - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_prepend_unichar: - * @string: a #GString - * @wc: a Unicode character - * - * Converts a Unicode character into UTF-8, and prepends it - * to the string. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_printf: - * @string: a #GString - * @format: the string format. See the printf() documentation - * @...: the parameters to insert into the format string - * - * Writes a formatted string into a #GString. - * This is similar to the standard sprintf() function, - * except that the #GString buffer automatically expands - * to contain the results. The previous contents of the - * #GString are destroyed. - */ - - -/** - * g_string_replace: - * @string: a #GString - * @find: the string to find in @string - * @replace: the string to insert in place of @find - * @limit: the maximum instances of @find to replace with @replace, or `0` for - * no limit - * - * Replaces the string @find with the string @replace in a #GString up to - * @limit times. If the number of instances of @find in the #GString is - * less than @limit, all instances are replaced. If @limit is `0`, - * all instances of @find are replaced. - * - * If @find is the empty string, since versions 2.69.1 and 2.68.4 the - * replacement will be inserted no more than once per possible position - * (beginning of string, end of string and between characters). This did - * not work correctly in earlier versions. - * - * Returns: the number of find and replace operations performed. - * Since: 2.68 - */ - - -/** - * g_string_set_size: - * @string: a #GString - * @len: the new length - * - * Sets the length of a #GString. If the length is less than - * the current length, the string will be truncated. If the - * length is greater than the current length, the contents - * of the newly added area are undefined. (However, as - * always, string->str[string->len] will be a nul byte.) - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_sized_new: (constructor) - * @dfl_size: the default size of the space allocated to hold the string - * - * Creates a new #GString, with enough space for @dfl_size - * bytes. This is useful if you are going to add a lot of - * text to the string and don't want it to be reallocated - * too often. - * - * Returns: (transfer full): the new #GString - */ - - -/** - * g_string_sprintf: - * @string: a #GString - * @format: the string format. See the sprintf() documentation - * @...: the parameters to insert into the format string - * - * Writes a formatted string into a #GString. - * This is similar to the standard sprintf() function, - * except that the #GString buffer automatically expands - * to contain the results. The previous contents of the - * #GString are destroyed. - * - * Deprecated: This function has been renamed to g_string_printf(). - */ - - -/** - * g_string_sprintfa: - * @string: a #GString - * @format: the string format. See the sprintf() documentation - * @...: the parameters to insert into the format string - * - * Appends a formatted string onto the end of a #GString. - * This function is similar to g_string_sprintf() except that - * the text is appended to the #GString. - * - * Deprecated: This function has been renamed to g_string_append_printf() - */ - - -/** - * g_string_truncate: - * @string: a #GString - * @len: the new size of @string - * - * Cuts off the end of the GString, leaving the first @len bytes. - * - * Returns: (transfer none): @string - */ - - -/** - * g_string_up: - * @string: a #GString - * - * Converts a #GString to uppercase. - * - * Returns: (transfer none): @string - * Deprecated: 2.2: This function uses the locale-specific - * toupper() function, which is almost never the right thing. - * Use g_string_ascii_up() or g_utf8_strup() instead. - */ - - -/** - * g_string_vprintf: - * @string: a #GString - * @format: (not nullable): the string format. See the printf() documentation - * @args: the parameters to insert into the format string - * - * Writes a formatted string into a #GString. - * This function is similar to g_string_printf() except that - * the arguments to the format string are passed as a va_list. - * - * Since: 2.14 - */ - - -/** - * g_strip_context: - * @msgid: a string - * @msgval: another string - * - * An auxiliary function for gettext() support (see Q_()). - * - * Returns: @msgval, unless @msgval is identical to @msgid - * and contains a '|' character, in which case a pointer to - * the substring of msgid after the first '|' character is returned. - * Since: 2.4 - */ - - -/** - * g_strjoin: - * @separator: (nullable): a string to insert between each of the - * strings, or %NULL - * @...: a %NULL-terminated list of strings to join - * - * Joins a number of strings together to form one long string, with the - * optional @separator inserted between each of them. The returned string - * should be freed with g_free(). - * - * Returns: a newly-allocated string containing all of the strings joined - * together, with @separator between them - */ - - -/** - * g_strjoinv: - * @separator: (nullable): a string to insert between each of the - * strings, or %NULL - * @str_array: a %NULL-terminated array of strings to join - * - * Joins a number of strings together to form one long string, with the - * optional @separator inserted between each of them. The returned string - * should be freed with g_free(). - * - * If @str_array has no items, the return value will be an - * empty string. If @str_array contains a single item, @separator will not - * appear in the resulting string. - * - * Returns: a newly-allocated string containing all of the strings joined - * together, with @separator between them - */ - - -/** - * g_strlcat: - * @dest: destination buffer, already containing one nul-terminated string - * @src: source buffer - * @dest_size: length of @dest buffer in bytes (not length of existing string - * inside @dest) - * - * Portability wrapper that calls strlcat() on systems which have it, - * and emulates it otherwise. Appends nul-terminated @src string to @dest, - * guaranteeing nul-termination for @dest. The total size of @dest won't - * exceed @dest_size. - * - * At most @dest_size - 1 characters will be copied. Unlike strncat(), - * @dest_size is the full size of dest, not the space left over. This - * function does not allocate memory. It always nul-terminates (unless - * @dest_size == 0 or there were no nul characters in the @dest_size - * characters of dest to start with). - * - * Caveat: this is supposedly a more secure alternative to strcat() or - * strncat(), but for real security g_strconcat() is harder to mess up. - * - * Returns: size of attempted result, which is MIN (dest_size, strlen - * (original dest)) + strlen (src), so if retval >= dest_size, - * truncation occurred. - */ - - -/** - * g_strlcpy: - * @dest: destination buffer - * @src: source buffer - * @dest_size: length of @dest in bytes - * - * Portability wrapper that calls strlcpy() on systems which have it, - * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is - * guaranteed to be nul-terminated; @src must be nul-terminated; - * @dest_size is the buffer size, not the number of bytes to copy. - * - * At most @dest_size - 1 characters will be copied. Always nul-terminates - * (unless @dest_size is 0). This function does not allocate memory. Unlike - * strncpy(), this function doesn't pad @dest (so it's often faster). It - * returns the size of the attempted result, strlen (src), so if - * @retval >= @dest_size, truncation occurred. - * - * Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(), - * but if you really want to avoid screwups, g_strdup() is an even better - * idea. - * - * Returns: length of @src - */ - - -/** - * g_strncasecmp: - * @s1: a string - * @s2: a string to compare with @s1 - * @n: the maximum number of characters to compare - * - * A case-insensitive string comparison, corresponding to the standard - * strncasecmp() function on platforms which support it. It is similar - * to g_strcasecmp() except it only compares the first @n characters of - * the strings. - * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, - * or a positive value if @s1 > @s2. - * Deprecated: 2.2: The problem with g_strncasecmp() is that it does - * the comparison by calling toupper()/tolower(). These functions - * are locale-specific and operate on single bytes. However, it is - * impossible to handle things correctly from an internationalization - * standpoint by operating on bytes, since characters may be multibyte. - * Thus g_strncasecmp() is broken if your string is guaranteed to be - * ASCII, since it is locale-sensitive, and it's broken if your string - * is localized, since it doesn't work on many encodings at all, - * including UTF-8, EUC-JP, etc. - * - * There are therefore two replacement techniques: g_ascii_strncasecmp(), - * which only works on ASCII and is not locale-sensitive, and - * g_utf8_casefold() followed by strcmp() on the resulting strings, - * which is good for case-insensitive sorting of UTF-8. - */ - - -/** - * g_strndup: - * @str: the string to duplicate - * @n: the maximum number of bytes to copy from @str - * - * Duplicates the first @n bytes of a string, returning a newly-allocated - * buffer @n + 1 bytes long which will always be nul-terminated. If @str - * is less than @n bytes long the buffer is padded with nuls. If @str is - * %NULL it returns %NULL. The returned value should be freed when no longer - * needed. - * - * To copy a number of characters from a UTF-8 encoded string, - * use g_utf8_strncpy() instead. - * - * Returns: a newly-allocated buffer containing the first @n bytes - * of @str, nul-terminated - */ - - -/** - * g_strnfill: - * @length: the length of the new string - * @fill_char: the byte to fill the string with - * - * Creates a new string @length bytes long filled with @fill_char. - * The returned string should be freed when no longer needed. - * - * Returns: a newly-allocated string filled the @fill_char - */ - - -/** - * g_strreverse: - * @string: the string to reverse - * - * Reverses all of the bytes in a string. For example, - * `g_strreverse ("abcdef")` will result in "fedcba". - * - * Note that g_strreverse() doesn't work on UTF-8 strings - * containing multibyte characters. For that purpose, use - * g_utf8_strreverse(). - * - * Returns: the same pointer passed in as @string - */ - - -/** - * g_strrstr: - * @haystack: a nul-terminated string - * @needle: the nul-terminated string to search for - * - * Searches the string @haystack for the last occurrence - * of the string @needle. - * - * Returns: a pointer to the found occurrence, or - * %NULL if not found. - */ - - -/** - * g_strrstr_len: - * @haystack: a nul-terminated string - * @haystack_len: the maximum length of @haystack in bytes. A length of -1 - * can be used to mean "search the entire string", like g_strrstr(). - * @needle: the nul-terminated string to search for - * - * Searches the string @haystack for the last occurrence - * of the string @needle, limiting the length of the search - * to @haystack_len. - * - * Returns: a pointer to the found occurrence, or - * %NULL if not found. - */ - - -/** - * g_strsignal: - * @signum: the signal number. See the `signal` documentation - * - * Returns a string describing the given signal, e.g. "Segmentation fault". - * You should use this function in preference to strsignal(), because it - * returns a string in UTF-8 encoding, and since not all platforms support - * the strsignal() function. - * - * Returns: a UTF-8 string describing the signal. If the signal is unknown, - * it returns "unknown signal (<signum>)". - */ - - -/** - * g_strsplit: - * @string: a string to split - * @delimiter: a string which specifies the places at which to split - * the string. The delimiter is not included in any of the resulting - * strings, unless @max_tokens is reached. - * @max_tokens: the maximum number of pieces to split @string into. - * If this is less than 1, the string is split completely. - * - * Splits a string into a maximum of @max_tokens pieces, using the given - * @delimiter. If @max_tokens is reached, the remainder of @string is - * appended to the last token. - * - * As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a - * %NULL-terminated vector containing the six strings "", "a", "bc", "", "d" - * and "". - * - * As a special case, the result of splitting the empty string "" is an empty - * vector, not a vector containing a single string. The reason for this - * special case is that being able to represent an empty vector is typically - * more useful than consistent handling of empty elements. If you do need - * to represent empty elements, you'll need to check for the empty string - * before calling g_strsplit(). - * - * Returns: a newly-allocated %NULL-terminated array of strings. Use - * g_strfreev() to free it. - */ - - -/** - * g_strsplit_set: - * @string: The string to be tokenized - * @delimiters: A nul-terminated string containing bytes that are used - * to split the string (it can accept an empty string, which will result - * in no string splitting). - * @max_tokens: The maximum number of tokens to split @string into. - * If this is less than 1, the string is split completely - * - * Splits @string into a number of tokens not containing any of the characters - * in @delimiter. A token is the (possibly empty) longest string that does not - * contain any of the characters in @delimiters. If @max_tokens is reached, the - * remainder is appended to the last token. - * - * For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a - * %NULL-terminated vector containing the three strings "abc", "def", - * and "ghi". - * - * The result of g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated - * vector containing the four strings "", "def", "ghi", and "". - * - * As a special case, the result of splitting the empty string "" is an empty - * vector, not a vector containing a single string. The reason for this - * special case is that being able to represent an empty vector is typically - * more useful than consistent handling of empty elements. If you do need - * to represent empty elements, you'll need to check for the empty string - * before calling g_strsplit_set(). - * - * Note that this function works on bytes not characters, so it can't be used - * to delimit UTF-8 strings for anything but ASCII characters. - * - * Returns: a newly-allocated %NULL-terminated array of strings. Use - * g_strfreev() to free it. - * Since: 2.4 - */ - - -/** - * g_strstr_len: - * @haystack: a nul-terminated string - * @haystack_len: the maximum length of @haystack in bytes. A length of -1 - * can be used to mean "search the entire string", like `strstr()`. - * @needle: the string to search for - * - * Searches the string @haystack for the first occurrence - * of the string @needle, limiting the length of the search - * to @haystack_len. - * - * Returns: a pointer to the found occurrence, or - * %NULL if not found. - */ - - -/** - * g_strstrip: - * @string: a string to remove the leading and trailing whitespace from - * - * Removes leading and trailing whitespace from a string. - * See g_strchomp() and g_strchug(). - * - * Returns: @string - */ - - -/** - * g_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. - * It calls the standard strtod() function to handle the conversion, but - * if the string is not completely converted it attempts the conversion - * again with g_ascii_strtod(), and returns the best match. - * - * This function should seldom be used. The normal situation when reading - * numbers not for human consumption is to use g_ascii_strtod(). Only when - * you know that you must expect both locale formatted and C formatted numbers - * should you use this. Make sure that you don't pass strings such as comma - * separated lists of values, since the commas may be interpreted as a decimal - * point in some locales, causing unexpected results. - * - * Returns: the #gdouble value. - */ - - -/** - * g_strup: - * @string: the string to convert - * - * Converts a string to upper case. - * - * Returns: the string - * Deprecated: 2.2: This function is totally broken for the reasons - * discussed in the g_strncasecmp() docs - use g_ascii_strup() - * or g_utf8_strup() instead. - */ - - -/** - * g_strv_builder_add: - * @builder: a #GStrvBuilder - * @value: a string. - * - * Add a string to the end of the array. - * - * Since 2.68 - */ - - -/** - * g_strv_builder_add_many: - * @builder: a #GStrvBuilder - * @...: one or more strings followed by %NULL - * - * Appends all the given strings to the builder. - * - * Since 2.70 - */ - - -/** - * g_strv_builder_addv: - * @builder: a #GStrvBuilder - * @value: (array zero-terminated=1): the vector of strings to add - * - * Appends all the strings in the given vector to the builder. - * - * Since 2.70 - */ - - -/** - * g_strv_builder_end: - * @builder: a #GStrvBuilder - * - * Ends the builder process and returns the constructed NULL-terminated string - * array. The returned value should be freed with g_strfreev() when no longer - * needed. - * - * Returns: (transfer full): the constructed string array. - * - * Since 2.68 - */ - - -/** - * g_strv_builder_new: - * - * Creates a new #GStrvBuilder with a reference count of 1. - * Use g_strv_builder_unref() on the returned value when no longer needed. - * - * Returns: (transfer full): the new #GStrvBuilder - * Since: 2.68 - */ - - -/** - * g_strv_builder_ref: - * @builder: (transfer none): a #GStrvBuilder - * - * Atomically increments the reference count of @builder by one. - * This function is thread-safe and may be called from any thread. - * - * Returns: (transfer full): The passed in #GStrvBuilder - * Since: 2.68 - */ - - -/** - * g_strv_builder_unref: - * @builder: (transfer full): a #GStrvBuilder allocated by g_strv_builder_new() - * - * Decreases the reference count on @builder. - * - * In the event that there are no more references, releases all memory - * associated with the #GStrvBuilder. - * - * Since: 2.68 - */ - - -/** - * g_strv_contains: - * @strv: a %NULL-terminated array of strings - * @str: a string - * - * Checks if @strv contains @str. @strv must not be %NULL. - * - * Returns: %TRUE if @str is an element of @strv, according to g_str_equal(). - * Since: 2.44 - */ - - -/** - * g_strv_equal: - * @strv1: a %NULL-terminated array of strings - * @strv2: another %NULL-terminated array of strings - * - * Checks if @strv1 and @strv2 contain exactly the same elements in exactly the - * same order. Elements are compared using g_str_equal(). To match independently - * of order, sort the arrays first (using g_qsort_with_data() or similar). - * - * Two empty arrays are considered equal. Neither @strv1 not @strv2 may be - * %NULL. - * - * Returns: %TRUE if @strv1 and @strv2 are equal - * Since: 2.60 - */ - - -/** - * g_strv_length: - * @str_array: a %NULL-terminated array of strings - * - * Returns the length of the given %NULL-terminated - * string array @str_array. @str_array must not be %NULL. - * - * Returns: length of @str_array. - * Since: 2.6 - */ - - -/** - * g_test_add_data_func: - * @testpath: /-separated test case path name for the test. - * @test_data: Test data argument for the test function. - * @test_func: (scope async): The test function to invoke for this test. - * - * Create a new test case, similar to g_test_create_case(). However - * the test is assumed to use no fixture, and test suites are automatically - * created on the fly and added to the root fixture, based on the - * slash-separated portions of @testpath. The @test_data argument - * will be passed as first argument to @test_func. - * - * If @testpath includes the component "subprocess" anywhere in it, - * the test will be skipped by default, and only run if explicitly - * required via the `-p` command-line option or g_test_trap_subprocess(). - * - * No component of @testpath may start with a dot (`.`) if the - * %G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to - * do so even if it isn’t. - * - * Since: 2.16 - */ - - -/** - * g_test_add_data_func_full: - * @testpath: /-separated test case path name for the test. - * @test_data: Test data argument for the test function. - * @test_func: The test function to invoke for this test. - * @data_free_func: #GDestroyNotify for @test_data. - * - * Create a new test case, as with g_test_add_data_func(), but freeing - * @test_data after the test run is complete. - * - * Since: 2.34 - */ - - -/** - * g_test_add_func: - * @testpath: /-separated test case path name for the test. - * @test_func: (scope async): The test function to invoke for this test. - * - * Create a new test case, similar to g_test_create_case(). However - * the test is assumed to use no fixture, and test suites are automatically - * created on the fly and added to the root fixture, based on the - * slash-separated portions of @testpath. - * - * If @testpath includes the component "subprocess" anywhere in it, - * the test will be skipped by default, and only run if explicitly - * required via the `-p` command-line option or g_test_trap_subprocess(). - * - * No component of @testpath may start with a dot (`.`) if the - * %G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to - * do so even if it isn’t. - * - * Since: 2.16 - */ - - -/** - * g_test_assert_expected_messages: - * - * Asserts that all messages previously indicated via - * g_test_expect_message() have been seen and suppressed. - * - * This API may only be used with the old logging API (g_log() without - * %G_LOG_USE_STRUCTURED defined). It will not work with the structured logging - * API. See [Testing for Messages][testing-for-messages]. - * - * If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly - * expected via g_test_expect_message() then they will be ignored. - * - * Since: 2.34 - */ - - -/** - * g_test_bug: - * @bug_uri_snippet: Bug specific bug tracker URI or URI portion. - * - * This function adds a message to test reports that - * associates a bug URI with a test case. - * - * Bug URIs are constructed from a base URI set with g_test_bug_base() - * and @bug_uri_snippet. If g_test_bug_base() has not been called, it is - * assumed to be the empty string, so a full URI can be provided to - * g_test_bug() instead. - * - * Since GLib 2.70, the base URI is not prepended to @bug_uri_snippet if it - * is already a valid URI. - * - * Since: 2.16: - * See also: g_test_summary() - */ - - -/** - * g_test_bug_base: - * @uri_pattern: the base pattern for bug URIs - * - * Specify the base URI for bug reports. - * - * The base URI is used to construct bug report messages for - * g_test_message() when g_test_bug() is called. - * Calling this function outside of a test case sets the - * default base URI for all test cases. Calling it from within - * a test case changes the base URI for the scope of the test - * case only. - * Bug URIs are constructed by appending a bug specific URI - * portion to @uri_pattern, or by replacing the special string - * `%s` within @uri_pattern if that is present. - * - * If g_test_bug_base() is not called, bug URIs are formed solely - * from the value provided by g_test_bug(). - * - * Since: 2.16 - */ - - -/** - * g_test_build_filename: - * @file_type: the type of file (built vs. distributed) - * @first_path: the first segment of the pathname - * @...: %NULL-terminated additional path segments - * - * Creates the pathname to a data file that is required for a test. - * - * This function is conceptually similar to g_build_filename() except - * that the first argument has been replaced with a #GTestFileType - * argument. - * - * The data file should either have been distributed with the module - * containing the test (%G_TEST_DIST) or built as part of the build - * system of that module (%G_TEST_BUILT). - * - * In order for this function to work in srcdir != builddir situations, - * the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to - * have been defined. As of 2.38, this is done by the glib.mk - * included in GLib. Please ensure that your copy is up to date before - * using this function. - * - * In case neither variable is set, this function will fall back to - * using the dirname portion of argv[0], possibly removing ".libs". - * This allows for casual running of tests directly from the commandline - * in the srcdir == builddir case and should also support running of - * installed tests, assuming the data files have been installed in the - * same relative path as the test binary. - * - * Returns: the path of the file, to be freed using g_free() - * Since: 2.38 - */ - - -/** - * g_test_case_free: - * @test_case: a #GTestCase - * - * Free the @test_case. - * - * Since: 2.70 - */ - - -/** - * g_test_create_case: - * @test_name: the name for the test case - * @data_size: the size of the fixture data structure - * @test_data: test data argument for the test functions - * @data_setup: (scope async): the function to set up the fixture data - * @data_test: (scope async): the actual test function - * @data_teardown: (scope async): the function to teardown the fixture data - * - * Create a new #GTestCase, named @test_name. - * - * This API is fairly low level, and calling g_test_add() or g_test_add_func() - * is preferable. - * - * When this test is executed, a fixture structure of size @data_size - * will be automatically allocated and filled with zeros. Then @data_setup is - * called to initialize the fixture. After fixture setup, the actual test - * function @data_test is called. Once the test run completes, the - * fixture structure is torn down by calling @data_teardown and - * after that the memory is automatically released by the test framework. - * - * Splitting up a test run into fixture setup, test function and - * fixture teardown is most useful if the same fixture type is used for - * multiple tests. In this cases, g_test_create_case() will be - * called with the same type of fixture (the @data_size argument), but varying - * @test_name and @data_test arguments. - * - * Returns: a newly allocated #GTestCase. - * Since: 2.16 - */ - - -/** - * g_test_create_suite: - * @suite_name: a name for the suite - * - * Create a new test suite with the name @suite_name. - * - * Returns: A newly allocated #GTestSuite instance. - * Since: 2.16 - */ - - -/** - * g_test_expect_message: - * @log_domain: (nullable): the log domain of the message - * @log_level: the log level of the message - * @pattern: a glob-style [pattern][glib-Glob-style-pattern-matching] - * - * Indicates that a message with the given @log_domain and @log_level, - * with text matching @pattern, is expected to be logged. When this - * message is logged, it will not be printed, and the test case will - * not abort. - * - * This API may only be used with the old logging API (g_log() without - * %G_LOG_USE_STRUCTURED defined). It will not work with the structured logging - * API. See [Testing for Messages][testing-for-messages]. - * - * Use g_test_assert_expected_messages() to assert that all - * previously-expected messages have been seen and suppressed. - * - * You can call this multiple times in a row, if multiple messages are - * expected as a result of a single call. (The messages must appear in - * the same order as the calls to g_test_expect_message().) - * - * For example: - * - * |[<!-- language="C" --> - * // g_main_context_push_thread_default() should fail if the - * // context is already owned by another thread. - * g_test_expect_message (G_LOG_DOMAIN, - * G_LOG_LEVEL_CRITICAL, - * "assertion*acquired_context*failed"); - * g_main_context_push_thread_default (bad_context); - * g_test_assert_expected_messages (); - * ]| - * - * Note that you cannot use this to test g_error() messages, since - * g_error() intentionally never returns even if the program doesn't - * abort; use g_test_trap_subprocess() in this case. - * - * If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly - * expected via g_test_expect_message() then they will be ignored. - * - * Since: 2.34 - */ - - -/** - * g_test_fail: - * - * Indicates that a test failed. This function can be called - * multiple times from the same test. You can use this function - * if your test failed in a recoverable way. - * - * Do not use this function if the failure of a test could cause - * other tests to malfunction. - * - * Calling this function will not stop the test from running, you - * need to return from the test function yourself. So you can - * produce additional diagnostic messages or even continue running - * the test. - * - * If not called from inside a test, this function does nothing. - * - * Note that unlike g_test_skip() and g_test_incomplete(), this - * function does not log a message alongside the test failure. - * If details of the test failure are available, either log them with - * g_test_message() before g_test_fail(), or use g_test_fail_printf() - * instead. - * - * Since: 2.30 - */ - - -/** - * g_test_fail_printf: - * @format: the format string - * @...: printf-like arguments to @format - * - * Equivalent to g_test_fail(), but also record a message like - * g_test_skip_printf(). - * - * Since: 2.70 - */ - - -/** - * g_test_failed: - * - * Returns whether a test has already failed. This will - * be the case when g_test_fail(), g_test_incomplete() - * or g_test_skip() have been called, but also if an - * assertion has failed. - * - * This can be useful to return early from a test if - * continuing after a failed assertion might be harmful. - * - * The return value of this function is only meaningful - * if it is called from inside a test function. - * - * Returns: %TRUE if the test has failed - * Since: 2.38 - */ - - -/** - * g_test_get_dir: - * @file_type: the type of file (built vs. distributed) - * - * Gets the pathname of the directory containing test files of the type - * specified by @file_type. - * - * This is approximately the same as calling g_test_build_filename("."), - * but you don't need to free the return value. - * - * Returns: (type filename): the path of the directory, owned by GLib - * Since: 2.38 - */ - - -/** - * g_test_get_filename: - * @file_type: the type of file (built vs. distributed) - * @first_path: the first segment of the pathname - * @...: %NULL-terminated additional path segments - * - * Gets the pathname to a data file that is required for a test. - * - * This is the same as g_test_build_filename() with two differences. - * The first difference is that must only use this function from within - * a testcase function. The second difference is that you need not free - * the return value -- it will be automatically freed when the testcase - * finishes running. - * - * It is safe to use this function from a thread inside of a testcase - * but you must ensure that all such uses occur before the main testcase - * function returns (ie: it is best to ensure that all threads have been - * joined). - * - * Returns: the path, automatically freed at the end of the testcase - * Since: 2.38 - */ - - -/** - * g_test_get_path: - * - * Gets the test path for the test currently being run. - * - * In essence, it will be the same string passed as the first argument to - * e.g. g_test_add() when the test was added. - * - * This function returns a valid string only within a test function. - * - * Returns: the test path for the test currently being run - * Since: 2.68 - */ - - -/** - * g_test_get_root: - * - * Get the toplevel test suite for the test path API. - * - * Returns: the toplevel #GTestSuite - * Since: 2.16 - */ - - -/** - * g_test_incomplete: - * @msg: (nullable): explanation - * - * Indicates that a test failed because of some incomplete - * functionality. This function can be called multiple times - * from the same test. - * - * Calling this function will not stop the test from running, you - * need to return from the test function yourself. So you can - * produce additional diagnostic messages or even continue running - * the test. - * - * If not called from inside a test, this function does nothing. - * - * Since: 2.38 - */ - - -/** - * g_test_incomplete_printf: - * @format: the format string - * @...: printf-like arguments to @format - * - * Equivalent to g_test_incomplete(), but the explanation is formatted - * as if by g_strdup_printf(). - * - * Since: 2.70 - */ - - -/** - * g_test_init: - * @argc: Address of the @argc parameter of the main() function. - * Changed if any arguments were handled. - * @argv: Address of the @argv parameter of main(). - * Any parameters understood by g_test_init() stripped before return. - * @...: %NULL-terminated list of special options, documented below. - * - * Initialize the GLib testing framework, e.g. by seeding the - * test random number generator, the name for g_get_prgname() - * and parsing test related command line args. - * - * So far, the following arguments are understood: - * - * - `-l`: List test cases available in a test executable. - * - `--seed=SEED`: Provide a random seed to reproduce test - * runs using random numbers. - * - `--verbose`: Run tests verbosely. - * - `-q`, `--quiet`: Run tests quietly. - * - `-p PATH`: Execute all tests matching the given path. - * - `-s PATH`: Skip all tests matching the given path. - * This can also be used to force a test to run that would otherwise - * be skipped (ie, a test whose name contains "/subprocess"). - * - `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes: - * - * `perf`: Performance tests, may take long and report results (off by default). - * - * `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage - * (off by default). - * - * `quick`: Quick tests, should run really quickly and give good coverage (the default). - * - * `undefined`: Tests for undefined behaviour, may provoke programming errors - * under g_test_trap_subprocess() or g_test_expect_message() to check - * that appropriate assertions or warnings are given (the default). - * - * `no-undefined`: Avoid tests for undefined behaviour - * - * - `--debug-log`: Debug test logging output. - * - * Options which can be passed to @... are: - * - * - `"no_g_set_prgname"`: Causes g_test_init() to not call g_set_prgname(). - * - %G_TEST_OPTION_ISOLATE_DIRS: Creates a unique temporary directory for each - * unit test and uses g_set_user_dirs() to set XDG directories to point into - * that temporary directory for the duration of the unit test. See the - * documentation for %G_TEST_OPTION_ISOLATE_DIRS. - * - * Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined, - * g_test_init() will print an error and exit. This is to prevent no-op tests - * from being executed, as g_assert() is commonly (erroneously) used in unit - * tests, and is a no-op when compiled with `G_DISABLE_ASSERT`. Ensure your - * tests are compiled without `G_DISABLE_ASSERT` defined. - * - * Since: 2.16 - */ - - -/** - * g_test_initialized: - * - * Returns %TRUE if g_test_init() has been called. - * - * Returns: %TRUE if g_test_init() has been called. - * Since: 2.36 - */ - - -/** - * g_test_log_buffer_free: - * - * Internal function for gtester to free test log messages, no ABI guarantees provided. - */ - - -/** - * g_test_log_buffer_new: - * - * Internal function for gtester to decode test log messages, no ABI guarantees provided. - */ - - -/** - * g_test_log_buffer_pop: - * - * Internal function for gtester to retrieve test log messages, no ABI guarantees provided. - */ - - -/** - * g_test_log_buffer_push: - * - * Internal function for gtester to decode test log messages, no ABI guarantees provided. - */ - - -/** - * g_test_log_msg_free: - * - * Internal function for gtester to free test log messages, no ABI guarantees provided. - */ - - -/** - * g_test_log_set_fatal_handler: - * @log_func: the log handler function. - * @user_data: data passed to the log handler. - * - * Installs a non-error fatal log handler which can be - * used to decide whether log messages which are counted - * as fatal abort the program. - * - * The use case here is that you are running a test case - * that depends on particular libraries or circumstances - * and cannot prevent certain known critical or warning - * messages. So you install a handler that compares the - * domain and message to precisely not abort in such a case. - * - * Note that the handler is reset at the beginning of - * any test case, so you have to set it inside each test - * function which needs the special behavior. - * - * This handler has no effect on g_error messages. - * - * This handler also has no effect on structured log messages (using - * g_log_structured() or g_log_structured_array()). To change the fatal - * behaviour for specific log messages, programs must install a custom log - * writer function using g_log_set_writer_func().See - * [Using Structured Logging][using-structured-logging]. - * - * Since: 2.22 - */ - - -/** - * g_test_maximized_result: - * @maximized_quantity: the reported value - * @format: the format string of the report message - * @...: arguments to pass to the printf() function - * - * Report the result of a performance or measurement test. - * The test should generally strive to maximize the reported - * quantities (larger values are better than smaller ones), - * this and @maximized_quantity can determine sorting - * order for test result reports. - * - * Since: 2.16 - */ - - -/** - * g_test_message: - * @format: the format string - * @...: printf-like arguments to @format - * - * Add a message to the test report. - * - * Since: 2.16 - */ - - -/** - * g_test_minimized_result: - * @minimized_quantity: the reported value - * @format: the format string of the report message - * @...: arguments to pass to the printf() function - * - * Report the result of a performance or measurement test. - * The test should generally strive to minimize the reported - * quantities (smaller values are better than larger ones), - * this and @minimized_quantity can determine sorting - * order for test result reports. - * - * Since: 2.16 - */ - - -/** - * g_test_perf: - * - * Returns %TRUE if tests are run in performance mode. - * - * By default, tests are run in quick mode. In tests that use - * g_test_init(), the option `-m perf` enables performance tests, while - * `-m quick` disables them. - * - * Returns: %TRUE if in performance mode - */ - - -/** - * g_test_queue_destroy: - * @destroy_func: Destroy callback for teardown phase. - * @destroy_data: Destroy callback data. - * - * This function enqueus a callback @destroy_func to be executed - * during the next test case teardown phase. This is most useful - * to auto destruct allocated test resources at the end of a test run. - * Resources are released in reverse queue order, that means enqueueing - * callback A before callback B will cause B() to be called before - * A() during teardown. - * - * Since: 2.16 - */ - - -/** - * g_test_queue_free: - * @gfree_pointer: the pointer to be stored. - * - * Enqueue a pointer to be released with g_free() during the next - * teardown phase. This is equivalent to calling g_test_queue_destroy() - * with a destroy callback of g_free(). - * - * Since: 2.16 - */ - - -/** - * g_test_queue_unref: - * @gobject: the object to unref - * - * Enqueue an object to be released with g_object_unref() during - * the next teardown phase. This is equivalent to calling - * g_test_queue_destroy() with a destroy callback of g_object_unref(). - * - * Since: 2.16 - */ - - -/** - * g_test_quick: - * - * Returns %TRUE if tests are run in quick mode. - * Exactly one of g_test_quick() and g_test_slow() is active in any run; - * there is no "medium speed". - * - * By default, tests are run in quick mode. In tests that use - * g_test_init(), the options `-m quick`, `-m slow` and `-m thorough` - * can be used to change this. - * - * Returns: %TRUE if in quick mode - */ - - -/** - * g_test_quiet: - * - * Returns %TRUE if tests are run in quiet mode. - * In tests that use g_test_init(), the option `-q` or `--quiet` enables - * this, while `--verbose` disables it. - * The default is neither g_test_verbose() nor g_test_quiet(). - * - * Returns: %TRUE if in quiet mode - */ - - -/** - * g_test_rand_bit: - * - * Get a reproducible random bit (0 or 1), see g_test_rand_int() - * for details on test case random numbers. - * - * Since: 2.16 - */ - - -/** - * g_test_rand_double: - * - * Get a reproducible random floating point number, - * see g_test_rand_int() for details on test case random numbers. - * - * Returns: a random number from the seeded random number generator. - * Since: 2.16 - */ - - -/** - * g_test_rand_double_range: - * @range_start: the minimum value returned by this function - * @range_end: the minimum value not returned by this function - * - * Get a reproducible random floating pointer number out of a specified range, - * see g_test_rand_int() for details on test case random numbers. - * - * Returns: a number with @range_start <= number < @range_end. - * Since: 2.16 - */ - - -/** - * g_test_rand_int: - * - * Get a reproducible random integer number. - * - * The random numbers generated by the g_test_rand_*() family of functions - * change with every new test program start, unless the --seed option is - * given when starting test programs. - * - * For individual test cases however, the random number generator is - * reseeded, to avoid dependencies between tests and to make --seed - * effective for all test cases. - * - * Returns: a random number from the seeded random number generator. - * Since: 2.16 - */ - - -/** - * g_test_rand_int_range: - * @begin: the minimum value returned by this function - * @end: the smallest value not to be returned by this function - * - * Get a reproducible random integer number out of a specified range, - * see g_test_rand_int() for details on test case random numbers. - * - * Returns: a number with @begin <= number < @end. - * Since: 2.16 - */ - - -/** - * g_test_run: - * - * Runs all tests under the toplevel suite which can be retrieved - * with g_test_get_root(). Similar to g_test_run_suite(), the test - * cases to be run are filtered according to test path arguments - * (`-p testpath` and `-s testpath`) as parsed by g_test_init(). - * g_test_run_suite() or g_test_run() may only be called once in a - * program. - * - * In general, the tests and sub-suites within each suite are run in - * the order in which they are defined. However, note that prior to - * GLib 2.36, there was a bug in the `g_test_add_*` - * functions which caused them to create multiple suites with the same - * name, meaning that if you created tests "/foo/simple", - * "/bar/simple", and "/foo/using-bar" in that order, they would get - * run in that order (since g_test_run() would run the first "/foo" - * suite, then the "/bar" suite, then the second "/foo" suite). As of - * 2.36, this bug is fixed, and adding the tests in that order would - * result in a running order of "/foo/simple", "/foo/using-bar", - * "/bar/simple". If this new ordering is sub-optimal (because it puts - * more-complicated tests before simpler ones, making it harder to - * figure out exactly what has failed), you can fix it by changing the - * test paths to group tests by suite in a way that will result in the - * desired running order. Eg, "/simple/foo", "/simple/bar", - * "/complex/foo-using-bar". - * - * However, you should never make the actual result of a test depend - * on the order that tests are run in. If you need to ensure that some - * particular code runs before or after a given test case, use - * g_test_add(), which lets you specify setup and teardown functions. - * - * If all tests are skipped or marked as incomplete (expected failures), - * this function will return 0 if producing TAP output, or 77 (treated - * as "skip test" by Automake) otherwise. - * - * Returns: 0 on success, 1 on failure (assuming it returns at all), - * 0 or 77 if all tests were skipped with g_test_skip() and/or - * g_test_incomplete() - * Since: 2.16 - */ - - -/** - * g_test_run_suite: - * @suite: a #GTestSuite - * - * Execute the tests within @suite and all nested #GTestSuites. - * The test suites to be executed are filtered according to - * test path arguments (`-p testpath` and `-s testpath`) as parsed by - * g_test_init(). See the g_test_run() documentation for more - * information on the order that tests are run in. - * - * g_test_run_suite() or g_test_run() may only be called once - * in a program. - * - * Returns: 0 on success - * Since: 2.16 - */ - - -/** - * g_test_set_nonfatal_assertions: - * - * Changes the behaviour of the various `g_assert_*()` macros, - * g_test_assert_expected_messages() and the various - * `g_test_trap_assert_*()` macros to not abort to program, but instead - * call g_test_fail() and continue. (This also changes the behavior of - * g_test_fail() so that it will not cause the test program to abort - * after completing the failed test.) - * - * Note that the g_assert_not_reached() and g_assert() macros are not - * affected by this. - * - * This function can only be called after g_test_init(). - * - * Since: 2.38 - */ - - -/** - * g_test_skip: - * @msg: (nullable): explanation - * - * Indicates that a test was skipped. - * - * Calling this function will not stop the test from running, you - * need to return from the test function yourself. So you can - * produce additional diagnostic messages or even continue running - * the test. - * - * If not called from inside a test, this function does nothing. - * - * Since: 2.38 - */ - - -/** - * g_test_skip_printf: - * @format: the format string - * @...: printf-like arguments to @format - * - * Equivalent to g_test_skip(), but the explanation is formatted - * as if by g_strdup_printf(). - * - * Since: 2.70 - */ - - -/** - * g_test_slow: - * - * Returns %TRUE if tests are run in slow mode. - * Exactly one of g_test_quick() and g_test_slow() is active in any run; - * there is no "medium speed". - * - * By default, tests are run in quick mode. In tests that use - * g_test_init(), the options `-m quick`, `-m slow` and `-m thorough` - * can be used to change this. - * - * Returns: the opposite of g_test_quick() - */ - - -/** - * g_test_subprocess: - * - * Returns %TRUE (after g_test_init() has been called) if the test - * program is running under g_test_trap_subprocess(). - * - * Returns: %TRUE if the test program is running under - * g_test_trap_subprocess(). - * Since: 2.38 - */ - - -/** - * g_test_suite_add: - * @suite: a #GTestSuite - * @test_case: a #GTestCase - * - * Adds @test_case to @suite. - * - * Since: 2.16 - */ - - -/** - * g_test_suite_add_suite: - * @suite: a #GTestSuite - * @nestedsuite: another #GTestSuite - * - * Adds @nestedsuite to @suite. - * - * Since: 2.16 - */ - - -/** - * g_test_suite_free: - * @suite: a #GTestSuite - * - * Free the @suite and all nested #GTestSuites. - * - * Since: 2.70 - */ - - -/** - * g_test_summary: - * @summary: One or two sentences summarising what the test checks, and how it - * checks it. - * - * Set the summary for a test, which describes what the test checks, and how it - * goes about checking it. This may be included in test report output, and is - * useful documentation for anyone reading the source code or modifying a test - * in future. It must be a single line. - * - * This should be called at the top of a test function. - * - * For example: - * |[<!-- language="C" --> - * static void - * test_array_sort (void) - * { - * g_test_summary ("Test my_array_sort() sorts the array correctly and stably, " - * "including testing zero length and one-element arrays."); - * - * … - * } - * ]| - * - * Since: 2.62: - * See also: g_test_bug() - */ - - -/** - * g_test_thorough: - * - * Returns %TRUE if tests are run in thorough mode, equivalent to - * g_test_slow(). - * - * By default, tests are run in quick mode. In tests that use - * g_test_init(), the options `-m quick`, `-m slow` and `-m thorough` - * can be used to change this. - * - * Returns: the same thing as g_test_slow() - */ - - -/** - * g_test_timer_elapsed: - * - * Get the time since the last start of the timer with g_test_timer_start(). - * - * Returns: the time since the last start of the timer, as a double - * Since: 2.16 - */ - - -/** - * g_test_timer_last: - * - * Report the last result of g_test_timer_elapsed(). - * - * Returns: the last result of g_test_timer_elapsed(), as a double - * Since: 2.16 - */ - - -/** - * g_test_timer_start: - * - * Start a timing test. Call g_test_timer_elapsed() when the task is supposed - * to be done. Call this function again to restart the timer. - * - * Since: 2.16 - */ - - -/** - * g_test_trap_assert_failed: - * - * Assert that the last test subprocess failed. - * See g_test_trap_subprocess(). - * - * This is sometimes used to test situations that are formally considered to - * be undefined behaviour, like inputs that fail a g_return_if_fail() - * check. In these situations you should skip the entire test, including the - * call to g_test_trap_subprocess(), unless g_test_undefined() returns %TRUE - * to indicate that undefined behaviour may be tested. - * - * Since: 2.16 - */ - - -/** - * g_test_trap_assert_passed: - * - * Assert that the last test subprocess passed. - * See g_test_trap_subprocess(). - * - * Since: 2.16 - */ - - -/** - * g_test_trap_assert_stderr: - * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] - * - * Assert that the stderr output of the last test subprocess - * matches @serrpattern. See g_test_trap_subprocess(). - * - * This is sometimes used to test situations that are formally - * considered to be undefined behaviour, like code that hits a - * g_assert() or g_error(). In these situations you should skip the - * entire test, including the call to g_test_trap_subprocess(), unless - * g_test_undefined() returns %TRUE to indicate that undefined - * behaviour may be tested. - * - * Since: 2.16 - */ - - -/** - * g_test_trap_assert_stderr_unmatched: - * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] - * - * Assert that the stderr output of the last test subprocess - * does not match @serrpattern. See g_test_trap_subprocess(). - * - * Since: 2.16 - */ - - -/** - * g_test_trap_assert_stdout: - * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] - * - * Assert that the stdout output of the last test subprocess matches - * @soutpattern. See g_test_trap_subprocess(). - * - * Since: 2.16 - */ - - -/** - * g_test_trap_assert_stdout_unmatched: - * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] - * - * Assert that the stdout output of the last test subprocess - * does not match @soutpattern. See g_test_trap_subprocess(). - * - * Since: 2.16 - */ - - -/** - * g_test_trap_fork: - * @usec_timeout: Timeout for the forked test in micro seconds. - * @test_trap_flags: Flags to modify forking behaviour. - * - * Fork the current test program to execute a test case that might - * not return or that might abort. - * - * If @usec_timeout is non-0, the forked test case is aborted and - * considered failing if its run time exceeds it. - * - * The forking behavior can be configured with the #GTestTrapFlags flags. - * - * In the following example, the test code forks, the forked child - * process produces some sample output and exits successfully. - * The forking parent process then asserts successful child program - * termination and validates child program outputs. - * - * |[<!-- language="C" --> - * static void - * test_fork_patterns (void) - * { - * if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR)) - * { - * g_print ("some stdout text: somagic17\n"); - * g_printerr ("some stderr text: semagic43\n"); - * exit (0); // successful test run - * } - * g_test_trap_assert_passed (); - * g_test_trap_assert_stdout ("*somagic17*"); - * g_test_trap_assert_stderr ("*semagic43*"); - * } - * ]| - * - * Returns: %TRUE for the forked child and %FALSE for the executing parent process. - * Since: 2.16 - * Deprecated: This function is implemented only on Unix platforms, - * and is not always reliable due to problems inherent in - * fork-without-exec. Use g_test_trap_subprocess() instead. - */ - - -/** - * g_test_trap_has_passed: - * - * Check the result of the last g_test_trap_subprocess() call. - * - * Returns: %TRUE if the last test subprocess terminated successfully. - * Since: 2.16 - */ - - -/** - * g_test_trap_reached_timeout: - * - * Check the result of the last g_test_trap_subprocess() call. - * - * Returns: %TRUE if the last test subprocess got killed due to a timeout. - * Since: 2.16 - */ - - -/** - * g_test_trap_subprocess: - * @test_path: (nullable): Test to run in a subprocess - * @usec_timeout: Timeout for the subprocess test in micro seconds. - * @test_flags: Flags to modify subprocess behaviour. - * - * Respawns the test program to run only @test_path in a subprocess. - * This can be used for a test case that might not return, or that - * might abort. - * - * If @test_path is %NULL then the same test is re-run in a subprocess. - * You can use g_test_subprocess() to determine whether the test is in - * a subprocess or not. - * - * @test_path can also be the name of the parent test, followed by - * "`/subprocess/`" and then a name for the specific subtest (or just - * ending with "`/subprocess`" if the test only has one child test); - * tests with names of this form will automatically be skipped in the - * parent process. - * - * If @usec_timeout is non-0, the test subprocess is aborted and - * considered failing if its run time exceeds it. - * - * The subprocess behavior can be configured with the - * #GTestSubprocessFlags flags. - * - * You can use methods such as g_test_trap_assert_passed(), - * g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to - * check the results of the subprocess. (But note that - * g_test_trap_assert_stdout() and g_test_trap_assert_stderr() - * cannot be used if @test_flags specifies that the child should - * inherit the parent stdout/stderr.) - * - * If your `main ()` needs to behave differently in - * the subprocess, you can call g_test_subprocess() (after calling - * g_test_init()) to see whether you are in a subprocess. - * - * The following example tests that calling - * `my_object_new(1000000)` will abort with an error - * message. - * - * |[<!-- language="C" --> - * static void - * test_create_large_object (void) - * { - * if (g_test_subprocess ()) - * { - * my_object_new (1000000); - * return; - * } - * - * // Reruns this same test in a subprocess - * g_test_trap_subprocess (NULL, 0, 0); - * g_test_trap_assert_failed (); - * g_test_trap_assert_stderr ("*ERROR*too large*"); - * } - * - * int - * main (int argc, char **argv) - * { - * g_test_init (&argc, &argv, NULL); - * - * g_test_add_func ("/myobject/create_large_object", - * test_create_large_object); - * return g_test_run (); - * } - * ]| - * - * Since: 2.38 - */ - - -/** - * g_test_undefined: - * - * Returns %TRUE if tests may provoke assertions and other formally-undefined - * behaviour, to verify that appropriate warnings are given. It might, in some - * cases, be useful to turn this off with if running tests under valgrind; - * in tests that use g_test_init(), the option `-m no-undefined` disables - * those tests, while `-m undefined` explicitly enables them (normally - * the default behaviour). - * - * Since GLib 2.68, if GLib was compiled with gcc or clang and - * [AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) - * is enabled, the default changes to not exercising undefined behaviour. - * - * Returns: %TRUE if tests may provoke programming errors - */ - - -/** - * g_test_verbose: - * - * Returns %TRUE if tests are run in verbose mode. - * In tests that use g_test_init(), the option `--verbose` enables this, - * while `-q` or `--quiet` disables it. - * The default is neither g_test_verbose() nor g_test_quiet(). - * - * Returns: %TRUE if in verbose mode - */ - - -/** - * g_thread_exit: - * @retval: the return value of this thread - * - * Terminates the current thread. - * - * If another thread is waiting for us using g_thread_join() then the - * waiting thread will be woken up and get @retval as the return value - * of g_thread_join(). - * - * Calling g_thread_exit() with a parameter @retval is equivalent to - * returning @retval from the function @func, as given to g_thread_new(). - * - * You must only call g_thread_exit() from a thread that you created - * yourself with g_thread_new() or related APIs. You must not call - * this function from a thread created with another threading library - * or or from within a #GThreadPool. - */ - - -/** - * g_thread_join: - * @thread: (transfer full): a #GThread - * - * Waits until @thread finishes, i.e. the function @func, as - * given to g_thread_new(), returns or g_thread_exit() is called. - * If @thread has already terminated, then g_thread_join() - * returns immediately. - * - * Any thread can wait for any other thread by calling g_thread_join(), - * not just its 'creator'. Calling g_thread_join() from multiple threads - * for the same @thread leads to undefined behaviour. - * - * The value returned by @func or given to g_thread_exit() is - * returned by this function. - * - * g_thread_join() consumes the reference to the passed-in @thread. - * This will usually cause the #GThread struct and associated resources - * to be freed. Use g_thread_ref() to obtain an extra reference if you - * want to keep the GThread alive beyond the g_thread_join() call. - * - * Returns: (transfer full): the return value of the thread - */ - - -/** - * g_thread_new: - * @name: (nullable): an (optional) name for the new thread - * @func: (closure data) (scope async): a function to execute in the new thread - * @data: (nullable): an argument to supply to the new thread - * - * This function creates a new thread. The new thread starts by invoking - * @func with the argument data. The thread will run until @func returns - * or until g_thread_exit() is called from the new thread. The return value - * of @func becomes the return value of the thread, which can be obtained - * with g_thread_join(). - * - * The @name can be useful for discriminating threads in a debugger. - * It is not used for other purposes and does not have to be unique. - * Some systems restrict the length of @name to 16 bytes. - * - * If the thread can not be created the program aborts. See - * g_thread_try_new() if you want to attempt to deal with failures. - * - * If you are using threads to offload (potentially many) short-lived tasks, - * #GThreadPool may be more appropriate than manually spawning and tracking - * multiple #GThreads. - * - * To free the struct returned by this function, use g_thread_unref(). - * Note that g_thread_join() implicitly unrefs the #GThread as well. - * - * New threads by default inherit their scheduler policy (POSIX) or thread - * priority (Windows) of the thread creating the new thread. - * - * This behaviour changed in GLib 2.64: before threads on Windows were not - * inheriting the thread priority but were spawned with the default priority. - * Starting with GLib 2.64 the behaviour is now consistent between Windows and - * POSIX and all threads inherit their parent thread's priority. - * - * Returns: (transfer full): the new #GThread - * Since: 2.32 - */ - - -/** - * g_thread_pool_free: - * @pool: a #GThreadPool - * @immediate: should @pool shut down immediately? - * @wait_: should the function wait for all tasks to be finished? - * - * Frees all resources allocated for @pool. - * - * If @immediate is %TRUE, no new task is processed for @pool. - * Otherwise @pool is not freed before the last task is processed. - * Note however, that no thread of this pool is interrupted while - * processing a task. Instead at least all still running threads - * can finish their tasks before the @pool is freed. - * - * If @wait_ is %TRUE, this function does not return before all - * tasks to be processed (dependent on @immediate, whether all - * or only the currently running) are ready. - * Otherwise this function returns immediately. - * - * After calling this function @pool must not be used anymore. - */ - - -/** - * g_thread_pool_get_max_idle_time: - * - * This function will return the maximum @interval that a - * thread will wait in the thread pool for new tasks before - * being stopped. - * - * If this function returns 0, threads waiting in the thread - * pool for new work are not stopped. - * - * Returns: the maximum @interval (milliseconds) to wait - * for new tasks in the thread pool before stopping the - * thread - * Since: 2.10 - */ - - -/** - * g_thread_pool_get_max_threads: - * @pool: a #GThreadPool - * - * Returns the maximal number of threads for @pool. - * - * Returns: the maximal number of threads - */ - - -/** - * g_thread_pool_get_max_unused_threads: - * - * Returns the maximal allowed number of unused threads. - * - * Returns: the maximal number of unused threads - */ - - -/** - * g_thread_pool_get_num_threads: - * @pool: a #GThreadPool - * - * Returns the number of threads currently running in @pool. - * - * Returns: the number of threads currently running - */ - - -/** - * g_thread_pool_get_num_unused_threads: - * - * Returns the number of currently unused threads. - * - * Returns: the number of currently unused threads - */ - - -/** - * g_thread_pool_move_to_front: - * @pool: a #GThreadPool - * @data: an unprocessed item in the pool - * - * Moves the item to the front of the queue of unprocessed - * items, so that it will be processed next. - * - * Returns: %TRUE if the item was found and moved - * Since: 2.46 - */ - - -/** - * g_thread_pool_new: - * @func: a function to execute in the threads of the new thread pool - * @user_data: user data that is handed over to @func every time it - * is called - * @max_threads: the maximal number of threads to execute concurrently - * in the new thread pool, -1 means no limit - * @exclusive: should this thread pool be exclusive? - * @error: return location for error, or %NULL - * - * This function creates a new thread pool. - * - * Whenever you call g_thread_pool_push(), either a new thread is - * created or an unused one is reused. At most @max_threads threads - * are running concurrently for this thread pool. @max_threads = -1 - * allows unlimited threads to be created for this thread pool. The - * newly created or reused thread now executes the function @func - * with the two arguments. The first one is the parameter to - * g_thread_pool_push() and the second one is @user_data. - * - * Pass g_get_num_processors() to @max_threads to create as many threads as - * there are logical processors on the system. This will not pin each thread to - * a specific processor. - * - * The parameter @exclusive determines whether the thread pool owns - * all threads exclusive or shares them with other thread pools. - * If @exclusive is %TRUE, @max_threads threads are started - * immediately and they will run exclusively for this thread pool - * until it is destroyed by g_thread_pool_free(). If @exclusive is - * %FALSE, threads are created when needed and shared between all - * non-exclusive thread pools. This implies that @max_threads may - * not be -1 for exclusive thread pools. Besides, exclusive thread - * pools are not affected by g_thread_pool_set_max_idle_time() - * since their threads are never considered idle and returned to the - * global pool. - * - * @error can be %NULL to ignore errors, or non-%NULL to report - * errors. An error can only occur when @exclusive is set to %TRUE - * and not all @max_threads threads could be created. - * See #GThreadError for possible errors that may occur. - * Note, even in case of error a valid #GThreadPool is returned. - * - * Returns: the new #GThreadPool - */ - - -/** - * g_thread_pool_new_full: - * @func: a function to execute in the threads of the new thread pool - * @user_data: user data that is handed over to @func every time it - * is called - * @item_free_func: (nullable): used to pass as a free function to - * g_async_queue_new_full() - * @max_threads: the maximal number of threads to execute concurrently - * in the new thread pool, `-1` means no limit - * @exclusive: should this thread pool be exclusive? - * @error: return location for error, or %NULL - * - * This function creates a new thread pool similar to g_thread_pool_new() - * but allowing @item_free_func to be specified to free the data passed - * to g_thread_pool_push() in the case that the #GThreadPool is stopped - * and freed before all tasks have been executed. - * - * Returns: (transfer full): the new #GThreadPool - * Since: 2.70 - */ - - -/** - * g_thread_pool_push: - * @pool: a #GThreadPool - * @data: a new task for @pool - * @error: return location for error, or %NULL - * - * Inserts @data into the list of tasks to be executed by @pool. - * - * When the number of currently running threads is lower than the - * maximal allowed number of threads, a new thread is started (or - * reused) with the properties given to g_thread_pool_new(). - * Otherwise, @data stays in the queue until a thread in this pool - * finishes its previous task and processes @data. - * - * @error can be %NULL to ignore errors, or non-%NULL to report - * errors. An error can only occur when a new thread couldn't be - * created. In that case @data is simply appended to the queue of - * work to do. - * - * Before version 2.32, this function did not return a success status. - * - * Returns: %TRUE on success, %FALSE if an error occurred - */ - - -/** - * g_thread_pool_set_max_idle_time: - * @interval: the maximum @interval (in milliseconds) - * a thread can be idle - * - * This function will set the maximum @interval that a thread - * waiting in the pool for new tasks can be idle for before - * being stopped. This function is similar to calling - * g_thread_pool_stop_unused_threads() on a regular timeout, - * except this is done on a per thread basis. - * - * By setting @interval to 0, idle threads will not be stopped. - * - * The default value is 15000 (15 seconds). - * - * Since: 2.10 - */ - - -/** - * g_thread_pool_set_max_threads: - * @pool: a #GThreadPool - * @max_threads: a new maximal number of threads for @pool, - * or -1 for unlimited - * @error: return location for error, or %NULL - * - * Sets the maximal allowed number of threads for @pool. - * A value of -1 means that the maximal number of threads - * is unlimited. If @pool is an exclusive thread pool, setting - * the maximal number of threads to -1 is not allowed. - * - * Setting @max_threads to 0 means stopping all work for @pool. - * It is effectively frozen until @max_threads is set to a non-zero - * value again. - * - * A thread is never terminated while calling @func, as supplied by - * g_thread_pool_new(). Instead the maximal number of threads only - * has effect for the allocation of new threads in g_thread_pool_push(). - * A new thread is allocated, whenever the number of currently - * running threads in @pool is smaller than the maximal number. - * - * @error can be %NULL to ignore errors, or non-%NULL to report - * errors. An error can only occur when a new thread couldn't be - * created. - * - * Before version 2.32, this function did not return a success status. - * - * Returns: %TRUE on success, %FALSE if an error occurred - */ - - -/** - * g_thread_pool_set_max_unused_threads: - * @max_threads: maximal number of unused threads - * - * Sets the maximal number of unused threads to @max_threads. - * If @max_threads is -1, no limit is imposed on the number - * of unused threads. - * - * The default value is 2. - */ - - -/** - * g_thread_pool_set_sort_function: - * @pool: a #GThreadPool - * @func: the #GCompareDataFunc used to sort the list of tasks. - * This function is passed two tasks. It should return - * 0 if the order in which they are handled does not matter, - * a negative value if the first task should be processed before - * the second or a positive value if the second task should be - * processed first. - * @user_data: user data passed to @func - * - * Sets the function used to sort the list of tasks. This allows the - * tasks to be processed by a priority determined by @func, and not - * just in the order in which they were added to the pool. - * - * Note, if the maximum number of threads is more than 1, the order - * that threads are executed cannot be guaranteed 100%. Threads are - * scheduled by the operating system and are executed at random. It - * cannot be assumed that threads are executed in the order they are - * created. - * - * Since: 2.10 - */ - - -/** - * g_thread_pool_stop_unused_threads: - * - * Stops all currently unused threads. This does not change the - * maximal number of unused threads. This function can be used to - * regularly stop all unused threads e.g. from g_timeout_add(). - */ - - -/** - * g_thread_pool_unprocessed: - * @pool: a #GThreadPool - * - * Returns the number of tasks still unprocessed in @pool. - * - * Returns: the number of unprocessed tasks - */ - - -/** - * g_thread_ref: - * @thread: a #GThread - * - * Increase the reference count on @thread. - * - * Returns: (transfer full): a new reference to @thread - * Since: 2.32 - */ - - -/** - * g_thread_self: - * - * This function returns the #GThread corresponding to the - * current thread. Note that this function does not increase - * the reference count of the returned struct. - * - * This function will return a #GThread even for threads that - * were not created by GLib (i.e. those created by other threading - * APIs). This may be useful for thread identification purposes - * (i.e. comparisons) but you must not use GLib functions (such - * as g_thread_join()) on these threads. - * - * Returns: (transfer none): the #GThread representing the current thread - */ - - -/** - * g_thread_supported: - * - * This macro returns %TRUE if the thread system is initialized, - * and %FALSE if it is not. - * - * For language bindings, g_thread_get_initialized() provides - * the same functionality as a function. - * - * Returns: %TRUE, if the thread system is initialized - */ - - -/** - * g_thread_try_new: - * @name: (nullable): an (optional) name for the new thread - * @func: (closure data) (scope async): a function to execute in the new thread - * @data: (nullable): an argument to supply to the new thread - * @error: return location for error, or %NULL - * - * This function is the same as g_thread_new() except that - * it allows for the possibility of failure. - * - * If a thread can not be created (due to resource limits), - * @error is set and %NULL is returned. - * - * Returns: (transfer full): the new #GThread, or %NULL if an error occurred - * Since: 2.32 - */ - - -/** - * g_thread_unref: - * @thread: (transfer full): a #GThread - * - * Decrease the reference count on @thread, possibly freeing all - * resources associated with it. - * - * Note that each thread holds a reference to its #GThread while - * it is running, so it is safe to drop your own reference to it - * if you don't need it anymore. - * - * Since: 2.32 - */ - - -/** - * g_thread_yield: - * - * Causes the calling thread to voluntarily relinquish the CPU, so - * that other threads can run. - * - * This function is often used as a method to make busy wait less evil. - */ - - -/** - * g_time_val_add: - * @time_: a #GTimeVal - * @microseconds: number of microseconds to add to @time - * - * Adds the given number of microseconds to @time_. @microseconds can - * also be negative to decrease the value of @time_. - * - * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use `guint64` for - * representing microseconds since the epoch, or use #GDateTime. - */ - - -/** - * g_time_val_from_iso8601: - * @iso_date: an ISO 8601 encoded date string - * @time_: (out): a #GTimeVal - * - * Converts a string containing an ISO 8601 encoded date and time - * to a #GTimeVal and puts it into @time_. - * - * @iso_date must include year, month, day, hours, minutes, and - * seconds. It can optionally include fractions of a second and a time - * zone indicator. (In the absence of any time zone indication, the - * timestamp is assumed to be in local time.) - * - * Any leading or trailing space in @iso_date is ignored. - * - * This function was deprecated, along with #GTimeVal itself, in GLib 2.62. - * Equivalent functionality is available using code like: - * |[ - * GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL); - * gint64 time_val = g_date_time_to_unix (dt); - * g_date_time_unref (dt); - * ]| - * - * Returns: %TRUE if the conversion was successful. - * Since: 2.12 - * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use - * g_date_time_new_from_iso8601() instead. - */ - - -/** - * g_time_val_to_iso8601: - * @time_: a #GTimeVal - * - * Converts @time_ into an RFC 3339 encoded string, relative to the - * Coordinated Universal Time (UTC). This is one of the many formats - * allowed by ISO 8601. - * - * ISO 8601 allows a large number of date/time formats, with or without - * punctuation and optional elements. The format returned by this function - * is a complete date and time, with optional punctuation included, the - * UTC time zone represented as "Z", and the @tv_usec part included if - * and only if it is nonzero, i.e. either - * "YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ". - * - * This corresponds to the Internet date/time format defined by - * [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt), - * and to either of the two most-precise formats defined by - * the W3C Note - * [Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827). - * Both of these documents are profiles of ISO 8601. - * - * Use g_date_time_format() or g_strdup_printf() if a different - * variation of ISO 8601 format is required. - * - * If @time_ represents a date which is too large to fit into a `struct tm`, - * %NULL will be returned. This is platform dependent. Note also that since - * `GTimeVal` stores the number of seconds as a `glong`, on 32-bit systems it - * is subject to the year 2038 problem. Accordingly, since GLib 2.62, this - * function has been deprecated. Equivalent functionality is available using: - * |[ - * GDateTime *dt = g_date_time_new_from_unix_utc (time_val); - * iso8601_string = g_date_time_format_iso8601 (dt); - * g_date_time_unref (dt); - * ]| - * - * The return value of g_time_val_to_iso8601() has been nullable since GLib - * 2.54; before then, GLib would crash under the same conditions. - * - * Returns: (nullable): a newly allocated string containing an ISO 8601 date, - * or %NULL if @time_ was too large - * Since: 2.12 - * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use - * g_date_time_format_iso8601(dt) instead. - */ - - -/** - * g_time_zone_adjust_time: - * @tz: a #GTimeZone - * @type: the #GTimeType of @time_ - * @time_: a pointer to a number of seconds since January 1, 1970 - * - * Finds an interval within @tz that corresponds to the given @time_, - * possibly adjusting @time_ if required to fit into an interval. - * The meaning of @time_ depends on @type. - * - * This function is similar to g_time_zone_find_interval(), with the - * difference that it always succeeds (by making the adjustments - * described below). - * - * In any of the cases where g_time_zone_find_interval() succeeds then - * this function returns the same value, without modifying @time_. - * - * This function may, however, modify @time_ in order to deal with - * non-existent times. If the non-existent local @time_ of 02:30 were - * requested on March 14th 2010 in Toronto then this function would - * adjust @time_ to be 03:00 and return the interval containing the - * adjusted time. - * - * Returns: the interval containing @time_, never -1 - * Since: 2.26 - */ - - -/** - * g_time_zone_find_interval: - * @tz: a #GTimeZone - * @type: the #GTimeType of @time_ - * @time_: a number of seconds since January 1, 1970 - * - * Finds an interval within @tz that corresponds to the given @time_. - * The meaning of @time_ depends on @type. - * - * If @type is %G_TIME_TYPE_UNIVERSAL then this function will always - * succeed (since universal time is monotonic and continuous). - * - * Otherwise @time_ is treated as local time. The distinction between - * %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in - * the case that the given @time_ is ambiguous. In Toronto, for example, - * 01:30 on November 7th 2010 occurred twice (once inside of daylight - * savings time and the next, an hour later, outside of daylight savings - * time). In this case, the different value of @type would result in a - * different interval being returned. - * - * It is still possible for this function to fail. In Toronto, for - * example, 02:00 on March 14th 2010 does not exist (due to the leap - * forward to begin daylight savings time). -1 is returned in that - * case. - * - * Returns: the interval containing @time_, or -1 in case of failure - * Since: 2.26 - */ - - -/** - * g_time_zone_get_abbreviation: - * @tz: a #GTimeZone - * @interval: an interval within the timezone - * - * Determines the time zone abbreviation to be used during a particular - * @interval of time in the time zone @tz. - * - * 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: the time zone abbreviation, which belongs to @tz - * Since: 2.26 - */ - - -/** - * g_time_zone_get_identifier: - * @tz: a #GTimeZone - * - * Get the identifier of this #GTimeZone, as passed to g_time_zone_new(). - * If the identifier passed at construction time was not recognised, `UTC` will - * be returned. If it was %NULL, the identifier of the local timezone at - * construction time will be returned. - * - * The identifier will be returned in the same format as provided at - * construction time: if provided as a time offset, that will be returned by - * this function. - * - * Returns: identifier for this timezone - * Since: 2.58 - */ - - -/** - * g_time_zone_get_offset: - * @tz: a #GTimeZone - * @interval: an interval within the timezone - * - * Determines the offset to UTC in effect during a particular @interval - * of time in the time zone @tz. - * - * The offset is the number of seconds that you add to UTC time to - * arrive at local time for @tz (ie: negative numbers for time zones - * west of GMT, positive numbers for east). - * - * Returns: the number of seconds that should be added to UTC to get the - * local time in @tz - * Since: 2.26 - */ - - -/** - * g_time_zone_is_dst: - * @tz: a #GTimeZone - * @interval: an interval within the timezone - * - * Determines if daylight savings time is in effect during a particular - * @interval of time in the time zone @tz. - * - * Returns: %TRUE if daylight savings time is in effect - * Since: 2.26 - */ - - -/** - * g_time_zone_new: - * @identifier: (nullable): a timezone identifier - * - * A version of g_time_zone_new_identifier() which returns the UTC time zone - * if @identifier could not be parsed or loaded. - * - * If you need to check whether @identifier was loaded successfully, use - * g_time_zone_new_identifier(). - * - * Returns: (transfer full) (not nullable): the requested timezone - * Deprecated: 2.68: Use g_time_zone_new_identifier() instead, as it provides - * error reporting. Change your code to handle a potentially %NULL return - * value. - * Since: 2.26 - */ - - -/** - * g_time_zone_new_identifier: - * @identifier: (nullable): a timezone identifier - * - * Creates a #GTimeZone corresponding to @identifier. If @identifier cannot be - * parsed or loaded, %NULL is returned. - * - * @identifier can either be an RFC3339/ISO 8601 time offset or - * something that would pass as a valid value for the `TZ` environment - * variable (including %NULL). - * - * In Windows, @identifier can also be the unlocalized name of a time - * zone for standard time, for example "Pacific Standard Time". - * - * Valid RFC3339 time offsets are `"Z"` (for UTC) or - * `"±hh:mm"`. ISO 8601 additionally specifies - * `"±hhmm"` and `"±hh"`. Offsets are - * time values to be added to Coordinated Universal Time (UTC) to get - * the local time. - * - * In UNIX, the `TZ` environment variable typically corresponds - * to the name of a file in the zoneinfo database, an absolute path to a file - * somewhere else, or a string in - * "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format. - * There are no spaces in the specification. The name of standard - * and daylight savings time zone must be three or more alphabetic - * characters. Offsets are time values to be added to local time to - * get Coordinated Universal Time (UTC) and should be - * `"[±]hh[[:]mm[:ss]]"`. Dates are either - * `"Jn"` (Julian day with n between 1 and 365, leap - * years not counted), `"n"` (zero-based Julian day - * with n between 0 and 365) or `"Mm.w.d"` (day d - * (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day - * 0 is a Sunday). Times are in local wall clock time, the default is - * 02:00:00. - * - * In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also - * accepts POSIX format. The Windows format uses US rules for all time - * zones; daylight savings time is 60 minutes behind the standard time - * with date and time of change taken from Pacific Standard Time. - * Offsets are time values to be added to the local time to get - * Coordinated Universal Time (UTC). - * - * g_time_zone_new_local() calls this function with the value of the - * `TZ` environment variable. This function itself is independent of - * the value of `TZ`, but if @identifier is %NULL then `/etc/localtime` - * will be consulted to discover the correct time zone on UNIX and the - * registry will be consulted or GetTimeZoneInformation() will be used - * to get the local time zone on Windows. - * - * If intervals are not available, only time zone rules from `TZ` - * environment variable or other means, then they will be computed - * from year 1900 to 2037. If the maximum year for the rules is - * available and it is greater than 2037, then it will followed - * instead. - * - * See - * [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6) - * for a precise definition of valid RFC3339 time offsets - * (the `time-offset` expansion) and ISO 8601 for the - * full list of valid time offsets. See - * [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html) - * for an explanation of the possible - * values of the `TZ` environment variable. See - * [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx) - * for the list of time zones on Windows. - * - * You should release the return value by calling g_time_zone_unref() - * when you are done with it. - * - * Returns: (transfer full) (nullable): the requested timezone, or %NULL on - * failure - * Since: 2.68 - */ - - -/** - * g_time_zone_new_local: - * - * Creates a #GTimeZone corresponding to local time. The local time - * zone may change between invocations to this function; for example, - * if the system administrator changes it. - * - * This is equivalent to calling g_time_zone_new() with the value of - * the `TZ` environment variable (including the possibility of %NULL). - * - * You should release the return value by calling g_time_zone_unref() - * when you are done with it. - * - * Returns: the local timezone - * Since: 2.26 - */ - - -/** - * g_time_zone_new_offset: - * @seconds: offset to UTC, in seconds - * - * Creates a #GTimeZone corresponding to the given constant offset from UTC, - * in seconds. - * - * This is equivalent to calling g_time_zone_new() with a string in the form - * `[+|-]hh[:mm[:ss]]`. - * - * Returns: (transfer full): a timezone at the given offset from UTC - * Since: 2.58 - */ - - -/** - * g_time_zone_new_utc: - * - * Creates a #GTimeZone corresponding to UTC. - * - * This is equivalent to calling g_time_zone_new() with a value like - * "Z", "UTC", "+00", etc. - * - * You should release the return value by calling g_time_zone_unref() - * when you are done with it. - * - * Returns: the universal timezone - * Since: 2.26 - */ - - -/** - * g_time_zone_ref: - * @tz: a #GTimeZone - * - * Increases the reference count on @tz. - * - * Returns: a new reference to @tz. - * Since: 2.26 - */ - - -/** - * g_time_zone_unref: - * @tz: a #GTimeZone - * - * Decreases the reference count on @tz. - * - * Since: 2.26 - */ - - -/** - * g_timeout_add: - * @interval: the time between calls to the function, in milliseconds - * (1/1000ths of a second) - * @function: function to call - * @data: data to pass to @function - * - * Sets a function to be called at regular intervals, with the default - * priority, %G_PRIORITY_DEFAULT. - * - * The given @function is called repeatedly until it returns %G_SOURCE_REMOVE - * or %FALSE, at which point the timeout is automatically destroyed and the - * function will not be called again. The first call to the function will be - * at the end of the first @interval. - * - * Note that timeout functions may be delayed, due to the processing of other - * event sources. Thus they should not be relied on for precise timing. - * After each call to the timeout function, the time of the next - * timeout is recalculated based on the current time and the given interval - * (it does not try to 'catch up' time lost in delays). - * - * See [memory management of sources][mainloop-memory-management] for details - * on how to handle the return value and memory management of @data. - * - * If you want to have a timer in the "seconds" range and do not care - * about the exact time of the first call of the timer, use the - * g_timeout_add_seconds() function; this function allows for more - * optimizations and more efficient system power usage. - * - * This internally creates a main loop source using g_timeout_source_new() - * and attaches it to the global #GMainContext using g_source_attach(), so - * the callback will be invoked in whichever thread is running that main - * context. You can do these steps manually if you need greater control or to - * use a custom main context. - * - * It is safe to call this function from any thread. - * - * The interval given is in terms of monotonic time, not wall clock - * time. See g_get_monotonic_time(). - * - * Returns: the ID (greater than 0) of the event source. - */ - - -/** - * g_timeout_add_full: (rename-to g_timeout_add) - * @priority: the priority of the timeout source. Typically this will be in - * the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. - * @interval: the time between calls to the function, in milliseconds - * (1/1000ths of a second) - * @function: function to call - * @data: data to pass to @function - * @notify: (nullable): function to call when the timeout is removed, or %NULL - * - * Sets a function to be called at regular intervals, with the given - * priority. The function is called repeatedly until it returns - * %FALSE, at which point the timeout is automatically destroyed and - * the function will not be called again. The @notify function is - * called when the timeout is destroyed. The first call to the - * function will be at the end of the first @interval. - * - * Note that timeout functions may be delayed, due to the processing of other - * event sources. Thus they should not be relied on for precise timing. - * After each call to the timeout function, the time of the next - * timeout is recalculated based on the current time and the given interval - * (it does not try to 'catch up' time lost in delays). - * - * See [memory management of sources][mainloop-memory-management] for details - * on how to handle the return value and memory management of @data. - * - * This internally creates a main loop source using g_timeout_source_new() - * and attaches it to the global #GMainContext using g_source_attach(), so - * the callback will be invoked in whichever thread is running that main - * context. You can do these steps manually if you need greater control or to - * use a custom main context. - * - * The interval given is in terms of monotonic time, not wall clock time. - * See g_get_monotonic_time(). - * - * Returns: the ID (greater than 0) of the event source. - */ - - -/** - * g_timeout_add_seconds: - * @interval: the time between calls to the function, in seconds - * @function: function to call - * @data: data to pass to @function - * - * Sets a function to be called at regular intervals with the default - * priority, %G_PRIORITY_DEFAULT. - * - * The function is called repeatedly until it returns %G_SOURCE_REMOVE - * or %FALSE, at which point the timeout is automatically destroyed - * and the function will not be called again. - * - * This internally creates a main loop source using - * g_timeout_source_new_seconds() and attaches it to the main loop context - * using g_source_attach(). You can do these steps manually if you need - * greater control. Also see g_timeout_add_seconds_full(). - * - * It is safe to call this function from any thread. - * - * Note that the first call of the timer may not be precise for timeouts - * of one second. If you need finer precision and have such a timeout, - * you may want to use g_timeout_add() instead. - * - * See [memory management of sources][mainloop-memory-management] for details - * on how to handle the return value and memory management of @data. - * - * The interval given is in terms of monotonic time, not wall clock - * time. See g_get_monotonic_time(). - * - * Returns: the ID (greater than 0) of the event source. - * Since: 2.14 - */ - - -/** - * g_timeout_add_seconds_full: (rename-to g_timeout_add_seconds) - * @priority: the priority of the timeout source. Typically this will be in - * the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. - * @interval: the time between calls to the function, in seconds - * @function: function to call - * @data: data to pass to @function - * @notify: (nullable): function to call when the timeout is removed, or %NULL - * - * Sets a function to be called at regular intervals, with @priority. - * - * The function is called repeatedly until it returns %G_SOURCE_REMOVE - * or %FALSE, at which point the timeout is automatically destroyed and - * the function will not be called again. - * - * Unlike g_timeout_add(), this function operates at whole second granularity. - * The initial starting point of the timer is determined by the implementation - * and the implementation is expected to group multiple timers together so that - * they fire all at the same time. To allow this grouping, the @interval to the - * first timer is rounded and can deviate up to one second from the specified - * interval. Subsequent timer iterations will generally run at the specified - * interval. - * - * Note that timeout functions may be delayed, due to the processing of other - * event sources. Thus they should not be relied on for precise timing. - * After each call to the timeout function, the time of the next - * timeout is recalculated based on the current time and the given @interval - * - * See [memory management of sources][mainloop-memory-management] for details - * on how to handle the return value and memory management of @data. - * - * If you want timing more precise than whole seconds, use g_timeout_add() - * instead. - * - * The grouping of timers to fire at the same time results in a more power - * and CPU efficient behavior so if your timer is in multiples of seconds - * and you don't require the first timer exactly one second from now, the - * use of g_timeout_add_seconds() is preferred over g_timeout_add(). - * - * This internally creates a main loop source using - * g_timeout_source_new_seconds() and attaches it to the main loop context - * using g_source_attach(). You can do these steps manually if you need - * greater control. - * - * It is safe to call this function from any thread. - * - * The interval given is in terms of monotonic time, not wall clock - * time. See g_get_monotonic_time(). - * - * Returns: the ID (greater than 0) of the event source. - * Since: 2.14 - */ - - -/** - * g_timeout_source_new: - * @interval: the timeout interval in milliseconds. - * - * Creates a new timeout 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. - * - * The interval given is in terms of monotonic time, not wall clock - * time. See g_get_monotonic_time(). - * - * Returns: the newly-created timeout source - */ - - -/** - * g_timeout_source_new_seconds: - * @interval: the timeout interval in seconds - * - * Creates a new timeout 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. - * - * The scheduling granularity/accuracy of this timeout source will be - * in seconds. - * - * The interval given is in terms of monotonic time, not wall clock time. - * See g_get_monotonic_time(). - * - * Returns: the newly-created timeout source - * Since: 2.14 - */ - - -/** - * g_timer_continue: - * @timer: a #GTimer. - * - * Resumes a timer that has previously been stopped with - * g_timer_stop(). g_timer_stop() must be called before using this - * function. - * - * Since: 2.4 - */ - - -/** - * g_timer_destroy: - * @timer: a #GTimer to destroy. - * - * Destroys a timer, freeing associated resources. - */ - - -/** - * g_timer_elapsed: - * @timer: a #GTimer. - * @microseconds: return location for the fractional part of seconds - * elapsed, in microseconds (that is, the total number - * of microseconds elapsed, modulo 1000000), or %NULL - * - * If @timer has been started but not stopped, obtains the time since - * the timer was started. If @timer has been stopped, obtains the - * elapsed time between the time it was started and the time it was - * stopped. The return value is the number of seconds elapsed, - * including any fractional part. The @microseconds out parameter is - * essentially useless. - * - * Returns: seconds elapsed as a floating point value, including any - * fractional part. - */ - - -/** - * g_timer_is_active: - * @timer: a #GTimer. - * - * Exposes whether the timer is currently active. - * - * Returns: %TRUE if the timer is running, %FALSE otherwise - * Since: 2.62 - */ - - -/** - * g_timer_new: - * - * Creates a new timer, and starts timing (i.e. g_timer_start() is - * implicitly called for you). - * - * Returns: a new #GTimer. - */ - - -/** - * g_timer_reset: - * @timer: a #GTimer. - * - * This function is useless; it's fine to call g_timer_start() on an - * already-started timer to reset the start time, so g_timer_reset() - * serves no purpose. - */ - - -/** - * g_timer_start: - * @timer: a #GTimer. - * - * Marks a start time, so that future calls to g_timer_elapsed() will - * report the time since g_timer_start() was called. g_timer_new() - * automatically marks the start time, so no need to call - * g_timer_start() immediately after creating the timer. - */ - - -/** - * g_timer_stop: - * @timer: a #GTimer. - * - * Marks an end time, so calls to g_timer_elapsed() will return the - * difference between this end time and the start time. - */ - - -/** - * g_trash_stack_height: - * @stack_p: a #GTrashStack - * - * Returns the height of a #GTrashStack. - * - * Note that execution of this function is of O(N) complexity - * where N denotes the number of items on the stack. - * - * Returns: the height of the stack - * Deprecated: 2.48: #GTrashStack is deprecated without replacement - */ - - -/** - * g_trash_stack_peek: - * @stack_p: a #GTrashStack - * - * Returns the element at the top of a #GTrashStack - * which may be %NULL. - * - * Returns: the element at the top of the stack - * Deprecated: 2.48: #GTrashStack is deprecated without replacement - */ - - -/** - * g_trash_stack_pop: - * @stack_p: a #GTrashStack - * - * Pops a piece of memory off a #GTrashStack. - * - * Returns: the element at the top of the stack - * Deprecated: 2.48: #GTrashStack is deprecated without replacement - */ - - -/** - * g_trash_stack_push: - * @stack_p: a #GTrashStack - * @data_p: (not nullable): the piece of memory to push on the stack - * - * Pushes a piece of memory onto a #GTrashStack. - * - * Deprecated: 2.48: #GTrashStack is deprecated without replacement - */ - - -/** - * g_tree_destroy: - * @tree: a #GTree - * - * Removes all keys and values from the #GTree and decreases its - * reference count by one. If keys and/or values are dynamically - * allocated, you should either free them first or create the #GTree - * using g_tree_new_full(). In the latter case the destroy functions - * you supplied will be called on all keys and values before destroying - * the #GTree. - */ - - -/** - * g_tree_foreach: - * @tree: a #GTree - * @func: the function to call for each node visited. - * If this function returns %TRUE, the traversal is stopped. - * @user_data: user data to pass to the function - * - * Calls the given function for each of the key/value pairs in the #GTree. - * The function is passed the key and value of each pair, and the given - * @data parameter. The tree is traversed in sorted order. - * - * The tree may not be modified while iterating over it (you can't - * add/remove items). To remove all items matching a predicate, you need - * to add each item to a list in your #GTraverseFunc as you walk over - * the tree, then walk the list and remove each item. - */ - - -/** - * g_tree_foreach_node: - * @tree: a #GTree - * @func: the function to call for each node visited. - * If this function returns %TRUE, the traversal is stopped. - * @user_data: user data to pass to the function - * - * Calls the given function for each of the nodes in the #GTree. - * The function is passed the pointer to the particular node, and the given - * @data parameter. The tree traversal happens in-order. - * - * The tree may not be modified while iterating over it (you can't - * add/remove items). To remove all items matching a predicate, you need - * to add each item to a list in your #GTraverseFunc as you walk over - * the tree, then walk the list and remove each item. - * - * Since: 2.68 - */ - - -/** - * g_tree_height: - * @tree: a #GTree - * - * Gets the height of a #GTree. - * - * If the #GTree contains no nodes, the height is 0. - * If the #GTree contains only one root node the height is 1. - * If the root node has children the height is 2, etc. - * - * Returns: the height of @tree - */ - - -/** - * g_tree_insert: - * @tree: a #GTree - * @key: the key to insert - * @value: the value corresponding to the key - * - * Inserts a key/value pair into a #GTree. - * - * Inserts a new key and value into a #GTree as g_tree_insert_node() does, - * only this function does not return the inserted or set node. - */ - - -/** - * g_tree_insert_node: - * @tree: a #GTree - * @key: the key to insert - * @value: the value corresponding to the key - * - * Inserts a key/value pair into a #GTree. - * - * If the given key already exists in the #GTree its corresponding value - * is set to the new value. If you supplied a @value_destroy_func when - * creating the #GTree, the old value is freed using that function. If - * you supplied a @key_destroy_func when creating the #GTree, the passed - * key is freed using that function. - * - * The tree is automatically 'balanced' as new key/value pairs are added, - * so that the distance from the root to every leaf is as small as possible. - * The cost of maintaining a balanced tree while inserting new key/value - * result in a O(n log(n)) operation where most of the other operations - * are O(log(n)). - * - * Returns: (transfer none): the inserted (or set) node. - * Since: 2.68 - */ - - -/** - * g_tree_lookup: - * @tree: a #GTree - * @key: the key to look up - * - * Gets the value corresponding to the given key. Since a #GTree is - * automatically balanced as key/value pairs are added, key lookup - * is O(log n) (where n is the number of key/value pairs in the tree). - * - * Returns: the value corresponding to the key, or %NULL - * if the key was not found - */ - - -/** - * g_tree_lookup_extended: - * @tree: a #GTree - * @lookup_key: the key to look up - * @orig_key: (out) (optional) (nullable): returns the original key - * @value: (out) (optional) (nullable): returns the value associated with the key - * - * Looks up a key in the #GTree, returning the original key and the - * associated value. This is useful if you need to free the memory - * allocated for the original key, for example before calling - * g_tree_remove(). - * - * Returns: %TRUE if the key was found in the #GTree - */ - - -/** - * g_tree_lookup_node: - * @tree: a #GTree - * @key: the key to look up - * - * Gets the tree node corresponding to the given key. Since a #GTree is - * automatically balanced as key/value pairs are added, key lookup - * is O(log n) (where n is the number of key/value pairs in the tree). - * - * Returns: (nullable) (transfer none): the tree node corresponding to - * the key, or %NULL if the key was not found - * Since: 2.68 - */ - - -/** - * g_tree_lower_bound: - * @tree: a #GTree - * @key: the key to calculate the lower bound for - * - * Gets the lower bound node corresponding to the given key, - * or %NULL if the tree is empty or all the nodes in the tree - * have keys that are strictly lower than the searched key. - * - * The lower bound is the first node that has its key greater - * than or equal to the searched key. - * - * Returns: (nullable) (transfer none): the tree node corresponding to - * the lower bound, or %NULL if the tree is empty or has only - * keys strictly lower than the searched key. - * Since: 2.68 - */ - - -/** - * g_tree_new: - * @key_compare_func: the function used to order the nodes in the #GTree. - * It should return values similar to the standard strcmp() function - - * 0 if the two arguments are equal, a negative value if the first argument - * comes before the second, or a positive value if the first argument comes - * after the second. - * - * Creates a new #GTree. - * - * Returns: a newly allocated #GTree - */ - - -/** - * g_tree_new_full: - * @key_compare_func: qsort()-style comparison function - * @key_compare_data: data to pass to comparison function - * @key_destroy_func: a function to free the memory allocated for the key - * used when removing the entry from the #GTree or %NULL if you don't - * want to supply such a function - * @value_destroy_func: a function to free the memory allocated for the - * value used when removing the entry from the #GTree or %NULL if you - * don't want to supply such a function - * - * Creates a new #GTree like g_tree_new() and allows to specify functions - * to free the memory allocated for the key and value that get called when - * removing the entry from the #GTree. - * - * Returns: a newly allocated #GTree - */ - - -/** - * g_tree_new_with_data: - * @key_compare_func: qsort()-style comparison function - * @key_compare_data: data to pass to comparison function - * - * Creates a new #GTree with a comparison function that accepts user data. - * See g_tree_new() for more details. - * - * Returns: a newly allocated #GTree - */ - - -/** - * g_tree_nnodes: - * @tree: a #GTree - * - * Gets the number of nodes in a #GTree. - * - * Returns: the number of nodes in @tree - */ - - -/** - * g_tree_node_first: - * @tree: a #GTree - * - * Returns the first in-order node of the tree, or %NULL - * for an empty tree. - * - * Returns: (nullable) (transfer none): the first node in the tree - * Since: 2.68 - */ - - -/** - * g_tree_node_key: - * @node: a #GTree node - * - * Gets the key stored at a particular tree node. - * - * Returns: (nullable) (transfer none): the key at the node. - * Since: 2.68 - */ - - -/** - * g_tree_node_last: - * @tree: a #GTree - * - * Returns the last in-order node of the tree, or %NULL - * for an empty tree. - * - * Returns: (nullable) (transfer none): the last node in the tree - * Since: 2.68 - */ - - -/** - * g_tree_node_next: - * @node: a #GTree node - * - * Returns the next in-order node of the tree, or %NULL - * if the passed node was already the last one. - * - * Returns: (nullable) (transfer none): the next node in the tree - * Since: 2.68 - */ - - -/** - * g_tree_node_previous: - * @node: a #GTree node - * - * Returns the previous in-order node of the tree, or %NULL - * if the passed node was already the first one. - * - * Returns: (nullable) (transfer none): the previous node in the tree - * Since: 2.68 - */ - - -/** - * g_tree_node_value: - * @node: a #GTree node - * - * Gets the value stored at a particular tree node. - * - * Returns: (nullable) (transfer none): the value at the node. - * Since: 2.68 - */ - - -/** - * g_tree_ref: - * @tree: a #GTree - * - * Increments the reference count of @tree by one. - * - * It is safe to call this function from any thread. - * - * Returns: the passed in #GTree - * Since: 2.22 - */ - - -/** - * g_tree_remove: - * @tree: a #GTree - * @key: the key to remove - * - * Removes a key/value pair from a #GTree. - * - * If the #GTree was created using g_tree_new_full(), the key and value - * are freed using the supplied destroy functions, otherwise you have to - * make sure that any dynamically allocated values are freed yourself. - * If the key does not exist in the #GTree, the function does nothing. - * - * The cost of maintaining a balanced tree while removing a key/value - * result in a O(n log(n)) operation where most of the other operations - * are O(log(n)). - * - * Returns: %TRUE if the key was found (prior to 2.8, this function - * returned nothing) - */ - - -/** - * g_tree_remove_all: - * @tree: a #GTree - * - * Removes all nodes from a #GTree and destroys their keys and values, - * then resets the #GTree’s root to %NULL. - * - * Since: 2.70 - */ - - -/** - * g_tree_replace: - * @tree: a #GTree - * @key: the key to insert - * @value: the value corresponding to the key - * - * Inserts a new key and value into a #GTree as g_tree_replace_node() does, - * only this function does not return the inserted or set node. - */ - - -/** - * g_tree_replace_node: - * @tree: a #GTree - * @key: the key to insert - * @value: the value corresponding to the key - * - * Inserts a new key and value into a #GTree similar to g_tree_insert_node(). - * The difference is that if the key already exists in the #GTree, it gets - * replaced by the new key. If you supplied a @value_destroy_func when - * creating the #GTree, the old value is freed using that function. If you - * supplied a @key_destroy_func when creating the #GTree, the old key is - * freed using that function. - * - * The tree is automatically 'balanced' as new key/value pairs are added, - * so that the distance from the root to every leaf is as small as possible. - * - * Returns: (transfer none): the inserted (or set) node. - * Since: 2.68 - */ - - -/** - * g_tree_search: - * @tree: a #GTree - * @search_func: a function used to search the #GTree - * @user_data: the data passed as the second argument to @search_func - * - * Searches a #GTree using @search_func. - * - * The @search_func is called with a pointer to the key of a key/value - * pair in the tree, and the passed in @user_data. If @search_func returns - * 0 for a key/value pair, then the corresponding value is returned as - * the result of g_tree_search(). If @search_func returns -1, searching - * will proceed among the key/value pairs that have a smaller key; if - * @search_func returns 1, searching will proceed among the key/value - * pairs that have a larger key. - * - * Returns: the value corresponding to the found key, or %NULL - * if the key was not found - */ - - -/** - * g_tree_search_node: - * @tree: a #GTree - * @search_func: a function used to search the #GTree - * @user_data: the data passed as the second argument to @search_func - * - * Searches a #GTree using @search_func. - * - * The @search_func is called with a pointer to the key of a key/value - * pair in the tree, and the passed in @user_data. If @search_func returns - * 0 for a key/value pair, then the corresponding node is returned as - * the result of g_tree_search(). If @search_func returns -1, searching - * will proceed among the key/value pairs that have a smaller key; if - * @search_func returns 1, searching will proceed among the key/value - * pairs that have a larger key. - * - * Returns: (nullable) (transfer none): the node corresponding to the - * found key, or %NULL if the key was not found - * Since: 2.68 - */ - - -/** - * g_tree_steal: - * @tree: a #GTree - * @key: the key to remove - * - * Removes a key and its associated value from a #GTree without calling - * the key and value destroy functions. - * - * If the key does not exist in the #GTree, the function does nothing. - * - * Returns: %TRUE if the key was found (prior to 2.8, this function - * returned nothing) - */ - - -/** - * g_tree_traverse: - * @tree: a #GTree - * @traverse_func: the function to call for each node visited. If this - * function returns %TRUE, the traversal is stopped. - * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER, - * %G_PRE_ORDER and %G_POST_ORDER - * @user_data: user data to pass to the function - * - * Calls the given function for each node in the #GTree. - * - * Deprecated: 2.2: The order of a balanced tree is somewhat arbitrary. - * If you just want to visit all nodes in sorted order, use - * g_tree_foreach() instead. If you really need to visit nodes in - * a different order, consider using an [n-ary tree][glib-N-ary-Trees]. - */ - - -/** - * g_tree_unref: - * @tree: a #GTree - * - * Decrements the reference count of @tree by one. - * If the reference count drops to 0, all keys and values will - * be destroyed (if destroy functions were specified) and all - * memory allocated by @tree will be released. - * - * It is safe to call this function from any thread. - * - * Since: 2.22 - */ - - -/** - * g_tree_upper_bound: - * @tree: a #GTree - * @key: the key to calculate the upper bound for - * - * Gets the upper bound node corresponding to the given key, - * or %NULL if the tree is empty or all the nodes in the tree - * have keys that are lower than or equal to the searched key. - * - * The upper bound is the first node that has its key strictly greater - * than the searched key. - * - * Returns: (nullable) (transfer none): the tree node corresponding to the - * upper bound, or %NULL if the tree is empty or has only keys - * lower than or equal to the searched key. - * Since: 2.68 - */ - - -/** - * g_try_malloc: - * @n_bytes: number of bytes to allocate. - * - * Attempts to allocate @n_bytes, and returns %NULL on failure. - * Contrast with g_malloc(), which aborts the program on failure. - * - * Returns: the allocated memory, or %NULL. - */ - - -/** - * g_try_malloc0: - * @n_bytes: number of bytes to allocate - * - * Attempts to allocate @n_bytes, initialized to 0's, and returns %NULL on - * failure. Contrast with g_malloc0(), which aborts the program on failure. - * - * Since: 2.8 - * Returns: the allocated memory, or %NULL - */ - - -/** - * g_try_malloc0_n: - * @n_blocks: the number of blocks to allocate - * @n_block_bytes: the size of each block in bytes - * - * This function is similar to g_try_malloc0(), allocating (@n_blocks * @n_block_bytes) bytes, - * but care is taken to detect possible overflow during multiplication. - * - * Since: 2.24 - * Returns: the allocated memory, or %NULL - */ - - -/** - * g_try_malloc_n: - * @n_blocks: the number of blocks to allocate - * @n_block_bytes: the size of each block in bytes - * - * This function is similar to g_try_malloc(), allocating (@n_blocks * @n_block_bytes) bytes, - * but care is taken to detect possible overflow during multiplication. - * - * Since: 2.24 - * Returns: the allocated memory, or %NULL. - */ - - -/** - * g_try_realloc: - * @mem: (nullable): previously-allocated memory, or %NULL. - * @n_bytes: number of bytes to allocate. - * - * Attempts to realloc @mem to a new size, @n_bytes, and returns %NULL - * on failure. Contrast with g_realloc(), which aborts the program - * on failure. - * - * If @mem is %NULL, behaves the same as g_try_malloc(). - * - * Returns: the allocated memory, or %NULL. - */ - - -/** - * g_try_realloc_n: - * @mem: (nullable): previously-allocated memory, or %NULL. - * @n_blocks: the number of blocks to allocate - * @n_block_bytes: the size of each block in bytes - * - * This function is similar to g_try_realloc(), allocating (@n_blocks * @n_block_bytes) bytes, - * but care is taken to detect possible overflow during multiplication. - * - * Since: 2.24 - * Returns: the allocated memory, or %NULL. - */ - - -/** - * g_ucs4_to_utf16: - * @str: a UCS-4 encoded string - * @len: the maximum length (number of characters) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (out) (optional): location to store number of - * bytes read, or %NULL. If an error occurs then the index of the invalid - * input is stored here. - * @items_written: (out) (optional): location to store number - * of #gunichar2 written, or %NULL. The value stored here does not include - * the trailing 0. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. - * - * Convert a string from UCS-4 to UTF-16. A 0 character will be - * added to the result after the converted text. - * - * Returns: (transfer full): a pointer to a newly allocated UTF-16 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. - */ - - -/** - * g_ucs4_to_utf8: - * @str: a UCS-4 encoded string - * @len: the maximum length (number of characters) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (out) (optional): location to store number of - * characters read, or %NULL. - * @items_written: (out) (optional): location to store number - * of bytes written or %NULL. The value here stored does not include the - * trailing 0 byte. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. - * - * Convert a string from a 32-bit fixed width representation as UCS-4. - * to UTF-8. The result will be terminated with a 0 byte. - * - * Returns: (transfer full): a pointer to a newly allocated UTF-8 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. In that case, @items_read - * will be set to the position of the first invalid input character. - */ - - -/** - * g_uint64_checked_add: - * @dest: a pointer to the #guint64 destination - * @a: the #guint64 left operand - * @b: the #guint64 right operand - * - * Performs a checked addition of @a and @b, storing the result in - * @dest. - * - * If the operation is successful, %TRUE is returned. If the operation - * overflows then the state of @dest is undefined and %FALSE is - * returned. - * - * Returns: %TRUE if there was no overflow - * Since: 2.48 - */ - - -/** - * g_uint64_checked_mul: - * @dest: a pointer to the #guint64 destination - * @a: the #guint64 left operand - * @b: the #guint64 right operand - * - * Performs a checked multiplication of @a and @b, storing the result in - * @dest. - * - * If the operation is successful, %TRUE is returned. If the operation - * overflows then the state of @dest is undefined and %FALSE is - * returned. - * - * Returns: %TRUE if there was no overflow - * Since: 2.48 - */ - - -/** - * g_uint_checked_add: - * @dest: a pointer to the #guint destination - * @a: the #guint left operand - * @b: the #guint right operand - * - * Performs a checked addition of @a and @b, storing the result in - * @dest. - * - * If the operation is successful, %TRUE is returned. If the operation - * overflows then the state of @dest is undefined and %FALSE is - * returned. - * - * Returns: %TRUE if there was no overflow - * Since: 2.48 - */ - - -/** - * g_uint_checked_mul: - * @dest: a pointer to the #guint destination - * @a: the #guint left operand - * @b: the #guint right operand - * - * Performs a checked multiplication of @a and @b, storing the result in - * @dest. - * - * If the operation is successful, %TRUE is returned. If the operation - * overflows then the state of @dest is undefined and %FALSE is - * returned. - * - * Returns: %TRUE if there was no overflow - * Since: 2.48 - */ - - -/** - * g_unichar_break_type: - * @c: a Unicode character - * - * Determines the break type of @c. @c should be a Unicode character - * (to derive a character from UTF-8 encoded text, use - * g_utf8_get_char()). The break type is used to find word and line - * breaks ("text boundaries"), Pango implements the Unicode boundary - * resolution algorithms and normally you would use a function such - * as pango_break() instead of caring about break types yourself. - * - * Returns: the break type of @c - */ - - -/** - * g_unichar_combining_class: - * @uc: a Unicode character - * - * Determines the canonical combining class of a Unicode character. - * - * Returns: the combining class of the character - * Since: 2.14 - */ - - -/** - * g_unichar_compose: - * @a: a Unicode character - * @b: a Unicode character - * @ch: (out) (not optional): return location for the composed character - * - * Performs a single composition step of the - * Unicode canonical composition algorithm. - * - * This function includes algorithmic Hangul Jamo composition, - * but it is not exactly the inverse of g_unichar_decompose(). - * No composition can have either of @a or @b equal to zero. - * To be precise, this function composes if and only if - * there exists a Primary Composite P which is canonically - * equivalent to the sequence <@a,@b>. See the Unicode - * Standard for the definition of Primary Composite. - * - * If @a and @b do not compose a new character, @ch is set to zero. - * - * See - * [UAX#15](http://unicode.org/reports/tr15/) - * for details. - * - * Returns: %TRUE if the characters could be composed - * Since: 2.30 - */ - - -/** - * g_unichar_decompose: - * @ch: a Unicode character - * @a: (out) (not optional): return location for the first component of @ch - * @b: (out) (not optional): return location for the second component of @ch - * - * Performs a single decomposition step of the - * Unicode canonical decomposition algorithm. - * - * This function does not include compatibility - * decompositions. It does, however, include algorithmic - * Hangul Jamo decomposition, as well as 'singleton' - * decompositions which replace a character by a single - * other character. In the case of singletons *@b will - * be set to zero. - * - * If @ch is not decomposable, *@a is set to @ch and *@b - * is set to zero. - * - * Note that the way Unicode decomposition pairs are - * defined, it is guaranteed that @b would not decompose - * further, but @a may itself decompose. To get the full - * canonical decomposition for @ch, one would need to - * recursively call this function on @a. Or use - * g_unichar_fully_decompose(). - * - * See - * [UAX#15](http://unicode.org/reports/tr15/) - * for details. - * - * Returns: %TRUE if the character could be decomposed - * Since: 2.30 - */ - - -/** - * g_unichar_digit_value: - * @c: a Unicode character - * - * Determines the numeric value of a character as a decimal - * digit. - * - * Returns: If @c is a decimal digit (according to - * g_unichar_isdigit()), its numeric value. Otherwise, -1. - */ - - -/** - * g_unichar_fully_decompose: - * @ch: a Unicode character. - * @compat: whether perform canonical or compatibility decomposition - * @result: (optional) (out caller-allocates): location to store decomposed result, or %NULL - * @result_len: length of @result - * - * Computes the canonical or compatibility decomposition of a - * Unicode character. For compatibility decomposition, - * pass %TRUE for @compat; for canonical decomposition - * pass %FALSE for @compat. - * - * The decomposed sequence is placed in @result. Only up to - * @result_len characters are written into @result. The length - * of the full decomposition (irrespective of @result_len) is - * returned by the function. For canonical decomposition, - * currently all decompositions are of length at most 4, but - * this may change in the future (very unlikely though). - * At any rate, Unicode does guarantee that a buffer of length - * 18 is always enough for both compatibility and canonical - * decompositions, so that is the size recommended. This is provided - * as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH. - * - * See - * [UAX#15](http://unicode.org/reports/tr15/) - * for details. - * - * Returns: the length of the full decomposition. - * Since: 2.30 - */ - - -/** - * g_unichar_get_mirror_char: - * @ch: a Unicode character - * @mirrored_ch: location to store the mirrored character - * - * In Unicode, some characters are "mirrored". This means that their - * images are mirrored horizontally in text that is laid out from right - * to left. For instance, "(" would become its mirror image, ")", in - * right-to-left text. - * - * If @ch has the Unicode mirrored property and there is another unicode - * character that typically has a glyph that is the mirror image of @ch's - * glyph and @mirrored_ch is set, it puts that character in the address - * pointed to by @mirrored_ch. Otherwise the original character is put. - * - * Returns: %TRUE if @ch has a mirrored character, %FALSE otherwise - * Since: 2.4 - */ - - -/** - * g_unichar_get_script: - * @ch: a Unicode character - * - * Looks up the #GUnicodeScript for a particular character (as defined - * by Unicode Standard Annex \#24). No check is made for @ch being a - * valid Unicode character; if you pass in invalid character, the - * result is undefined. - * - * This function is equivalent to pango_script_for_unichar() and the - * two are interchangeable. - * - * Returns: the #GUnicodeScript for the character. - * Since: 2.14 - */ - - -/** - * g_unichar_isalnum: - * @c: a Unicode character - * - * Determines whether a character is alphanumeric. - * Given some UTF-8 text, obtain a character value - * with g_utf8_get_char(). - * - * Returns: %TRUE if @c is an alphanumeric character - */ - - -/** - * g_unichar_isalpha: - * @c: a Unicode character - * - * Determines whether a character is alphabetic (i.e. a letter). - * Given some UTF-8 text, obtain a character value with - * g_utf8_get_char(). - * - * Returns: %TRUE if @c is an alphabetic character - */ - - -/** - * g_unichar_iscntrl: - * @c: a Unicode character - * - * Determines whether a character is a control character. - * Given some UTF-8 text, obtain a character value with - * g_utf8_get_char(). - * - * Returns: %TRUE if @c is a control character - */ - - -/** - * g_unichar_isdefined: - * @c: a Unicode character - * - * Determines if a given character is assigned in the Unicode - * standard. - * - * Returns: %TRUE if the character has an assigned value - */ - - -/** - * g_unichar_isdigit: - * @c: a Unicode character - * - * Determines whether a character is numeric (i.e. a digit). This - * covers ASCII 0-9 and also digits in other languages/scripts. Given - * some UTF-8 text, obtain a character value with g_utf8_get_char(). - * - * Returns: %TRUE if @c is a digit - */ - - -/** - * g_unichar_isgraph: - * @c: a Unicode character - * - * Determines whether a character is printable and not a space - * (returns %FALSE for control characters, format characters, and - * spaces). g_unichar_isprint() is similar, but returns %TRUE for - * spaces. Given some UTF-8 text, obtain a character value with - * g_utf8_get_char(). - * - * Returns: %TRUE if @c is printable unless it's a space - */ - - -/** - * g_unichar_islower: - * @c: a Unicode character - * - * Determines whether a character is a lowercase letter. - * Given some UTF-8 text, obtain a character value with - * g_utf8_get_char(). - * - * Returns: %TRUE if @c is a lowercase letter - */ - - -/** - * g_unichar_ismark: - * @c: a Unicode character - * - * Determines whether a character is a mark (non-spacing mark, - * combining mark, or enclosing mark in Unicode speak). - * Given some UTF-8 text, obtain a character value - * with g_utf8_get_char(). - * - * Note: in most cases where isalpha characters are allowed, - * ismark characters should be allowed to as they are essential - * for writing most European languages as well as many non-Latin - * scripts. - * - * Returns: %TRUE if @c is a mark character - * Since: 2.14 - */ - - -/** - * g_unichar_isprint: - * @c: a Unicode character - * - * Determines whether a character is printable. - * Unlike g_unichar_isgraph(), returns %TRUE for spaces. - * Given some UTF-8 text, obtain a character value with - * g_utf8_get_char(). - * - * Returns: %TRUE if @c is printable - */ - - -/** - * g_unichar_ispunct: - * @c: a Unicode character - * - * Determines whether a character is punctuation or a symbol. - * Given some UTF-8 text, obtain a character value with - * g_utf8_get_char(). - * - * Returns: %TRUE if @c is a punctuation or symbol character - */ - - -/** - * g_unichar_isspace: - * @c: a Unicode character - * - * Determines whether a character is a space, tab, or line separator - * (newline, carriage return, etc.). Given some UTF-8 text, obtain a - * character value with g_utf8_get_char(). - * - * (Note: don't use this to do word breaking; you have to use - * Pango or equivalent to get word breaking right, the algorithm - * is fairly complex.) - * - * Returns: %TRUE if @c is a space character - */ - - -/** - * g_unichar_istitle: - * @c: a Unicode character - * - * Determines if a character is titlecase. Some characters in - * Unicode which are composites, such as the DZ digraph - * have three case variants instead of just two. The titlecase - * form is used at the beginning of a word where only the - * first letter is capitalized. The titlecase form of the DZ - * digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z. - * - * Returns: %TRUE if the character is titlecase - */ - - -/** - * g_unichar_isupper: - * @c: a Unicode character - * - * Determines if a character is uppercase. - * - * Returns: %TRUE if @c is an uppercase character - */ - - -/** - * g_unichar_iswide: - * @c: a Unicode character - * - * Determines if a character is typically rendered in a double-width - * cell. - * - * Returns: %TRUE if the character is wide - */ - - -/** - * g_unichar_iswide_cjk: - * @c: a Unicode character - * - * Determines if a character is typically rendered in a double-width - * cell under legacy East Asian locales. If a character is wide according to - * g_unichar_iswide(), then it is also reported wide with this function, but - * the converse is not necessarily true. See the - * [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/) - * for details. - * - * If a character passes the g_unichar_iswide() test then it will also pass - * this test, but not the other way around. Note that some characters may - * pass both this test and g_unichar_iszerowidth(). - * - * Returns: %TRUE if the character is wide in legacy East Asian locales - * Since: 2.12 - */ - - -/** - * g_unichar_isxdigit: - * @c: a Unicode character. - * - * Determines if a character is a hexadecimal digit. - * - * Returns: %TRUE if the character is a hexadecimal digit - */ - - -/** - * g_unichar_iszerowidth: - * @c: a Unicode character - * - * Determines if a given character typically takes zero width when rendered. - * The return value is %TRUE for all non-spacing and enclosing marks - * (e.g., combining accents), format characters, zero-width - * space, but not U+00AD SOFT HYPHEN. - * - * A typical use of this function is with one of g_unichar_iswide() or - * g_unichar_iswide_cjk() to determine the number of cells a string occupies - * when displayed on a grid display (terminals). However, note that not all - * terminals support zero-width rendering of zero-width marks. - * - * Returns: %TRUE if the character has zero width - * Since: 2.14 - */ - - -/** - * g_unichar_to_utf8: - * @c: a Unicode character code - * @outbuf: (out caller-allocates) (optional): output buffer, must have at - * least 6 bytes of space. If %NULL, the length will be computed and - * returned and nothing will be written to @outbuf. - * - * Converts a single character to UTF-8. - * - * Returns: number of bytes written - */ - - -/** - * g_unichar_tolower: - * @c: a Unicode character. - * - * Converts a character to lower case. - * - * Returns: the result of converting @c to lower case. - * If @c is not an upperlower or titlecase character, - * or has no lowercase equivalent @c is returned unchanged. - */ - - -/** - * g_unichar_totitle: - * @c: a Unicode character - * - * Converts a character to the titlecase. - * - * Returns: the result of converting @c to titlecase. - * If @c is not an uppercase or lowercase character, - * @c is returned unchanged. - */ - - -/** - * g_unichar_toupper: - * @c: a Unicode character - * - * Converts a character to uppercase. - * - * Returns: the result of converting @c to uppercase. - * If @c is not a lowercase or titlecase character, - * or has no upper case equivalent @c is returned unchanged. - */ - - -/** - * g_unichar_type: - * @c: a Unicode character - * - * Classifies a Unicode character by type. - * - * Returns: the type of the character. - */ - - -/** - * g_unichar_validate: - * @ch: a Unicode character - * - * Checks whether @ch is a valid Unicode character. Some possible - * integer values of @ch will not be valid. 0 is considered a valid - * character, though it's normally a string terminator. - * - * Returns: %TRUE if @ch is a valid Unicode character - */ - - -/** - * g_unichar_xdigit_value: - * @c: a Unicode character - * - * Determines the numeric value of a character as a hexadecimal - * digit. - * - * Returns: If @c is a hex digit (according to - * g_unichar_isxdigit()), its numeric value. Otherwise, -1. - */ - - -/** - * g_unicode_canonical_decomposition: - * @ch: a Unicode character. - * @result_len: location to store the length of the return value. - * - * Computes the canonical decomposition of a Unicode character. - * - * Returns: a newly allocated string of Unicode characters. - * @result_len is set to the resulting length of the string. - * Deprecated: 2.30: Use the more flexible g_unichar_fully_decompose() - * instead. - */ - - -/** - * g_unicode_canonical_ordering: - * @string: a UCS-4 encoded string. - * @len: the maximum length of @string to use. - * - * Computes the canonical ordering of a string in-place. - * This rearranges decomposed characters in the string - * according to their combining classes. See the Unicode - * manual for more information. - */ - - -/** - * g_unicode_script_from_iso15924: - * @iso15924: a Unicode script - * - * Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter - * codes to scripts. For example, the code for Arabic is 'Arab'. - * This function accepts four letter codes encoded as a @guint32 in a - * big-endian fashion. That is, the code expected for Arabic is - * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). - * - * See - * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) - * for details. - * - * Returns: the Unicode script for @iso15924, or - * of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and - * %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown. - * Since: 2.30 - */ - - -/** - * g_unicode_script_to_iso15924: - * @script: a Unicode script - * - * Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter - * codes to scripts. For example, the code for Arabic is 'Arab'. The - * four letter codes are encoded as a @guint32 by this function in a - * big-endian fashion. That is, the code returned for Arabic is - * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). - * - * See - * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) - * for details. - * - * Returns: the ISO 15924 code for @script, encoded as an integer, - * of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or - * ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood. - * Since: 2.30 - */ - - -/** - * g_unix_fd_add: - * @fd: a file descriptor - * @condition: IO conditions to watch for on @fd - * @function: a #GUnixFDSourceFunc - * @user_data: data to pass to @function - * - * Sets a function to be called when the IO condition, as specified by - * @condition becomes true for @fd. - * - * @function will be called when the specified IO condition becomes - * %TRUE. The function is expected to clear whatever event caused the - * IO condition to become true and return %TRUE in order to be notified - * when it happens again. If @function returns %FALSE then the watch - * will be cancelled. - * - * The return value of this function can be passed to g_source_remove() - * to cancel the watch at any time that it exists. - * - * The source will never close the fd -- you must do it yourself. - * - * Returns: the ID (greater than 0) of the event source - * Since: 2.36 - */ - - -/** - * g_unix_fd_add_full: - * @priority: the priority of the source - * @fd: a file descriptor - * @condition: IO conditions to watch for on @fd - * @function: a #GUnixFDSourceFunc - * @user_data: data to pass to @function - * @notify: function to call when the idle is removed, or %NULL - * - * Sets a function to be called when the IO condition, as specified by - * @condition becomes true for @fd. - * - * This is the same as g_unix_fd_add(), except that it allows you to - * specify a non-default priority and a provide a #GDestroyNotify for - * @user_data. - * - * Returns: the ID (greater than 0) of the event source - * Since: 2.36 - */ - - -/** - * g_unix_fd_source_new: - * @fd: a file descriptor - * @condition: IO conditions to watch for on @fd - * - * Creates a #GSource to watch for a particular IO condition on a file - * descriptor. - * - * The source will never close the fd -- you must do it yourself. - * - * Returns: the newly created #GSource - * Since: 2.36 - */ - - -/** - * g_unix_get_passwd_entry: - * @user_name: the username to get the passwd file entry for - * @error: return location for a #GError, or %NULL - * - * Get the `passwd` file entry for the given @user_name using `getpwnam_r()`. - * This can fail if the given @user_name doesn’t exist. - * - * The returned `struct passwd` has been allocated using g_malloc() and should - * be freed using g_free(). The strings referenced by the returned struct are - * included in the same allocation, so are valid until the `struct passwd` is - * freed. - * - * This function is safe to call from multiple threads concurrently. - * - * You will need to include `pwd.h` to get the definition of `struct passwd`. - * - * Returns: (transfer full): passwd entry, or %NULL on error; free the returned - * value with g_free() - * Since: 2.64 - */ - - -/** - * g_unix_open_pipe: - * @fds: Array of two integers - * @flags: Bitfield of file descriptor flags, as for fcntl() - * @error: a #GError - * - * Similar to the UNIX pipe() call, but on modern systems like Linux - * uses the pipe2() system call, which atomically creates a pipe with - * the configured flags. The only supported flag currently is - * %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that - * must still be done separately with fcntl(). - * - * This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if - * for fcntl(); these are different on Linux/glibc. - * - * Returns: %TRUE on success, %FALSE if not (and errno will be set). - * Since: 2.30 - */ - - -/** - * g_unix_set_fd_nonblocking: - * @fd: A file descriptor - * @nonblock: If %TRUE, set the descriptor to be non-blocking - * @error: a #GError - * - * Control the non-blocking state of the given file descriptor, - * according to @nonblock. On most systems this uses %O_NONBLOCK, but - * on some older ones may use %O_NDELAY. - * - * Returns: %TRUE if successful - * Since: 2.30 - */ - - -/** - * g_unix_signal_add: - * @signum: Signal number - * @handler: Callback - * @user_data: Data for @handler - * - * A convenience function for g_unix_signal_source_new(), which - * attaches to the default #GMainContext. You can remove the watch - * using g_source_remove(). - * - * Returns: An ID (greater than 0) for the event source - * Since: 2.30 - */ - - -/** - * g_unix_signal_add_full: (rename-to g_unix_signal_add) - * @priority: the priority of the signal source. Typically this will be in - * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. - * @signum: Signal number - * @handler: Callback - * @user_data: Data for @handler - * @notify: #GDestroyNotify for @handler - * - * A convenience function for g_unix_signal_source_new(), which - * attaches to the default #GMainContext. You can remove the watch - * using g_source_remove(). - * - * Returns: An ID (greater than 0) for the event source - * Since: 2.30 - */ - - -/** - * g_unix_signal_source_new: - * @signum: A signal number - * - * Create a #GSource that will be dispatched upon delivery of the UNIX - * signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`, - * `SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2` - * were added. In GLib 2.54, `SIGWINCH` was added. - * - * Note that unlike the UNIX default, all sources which have created a - * watch will be dispatched, regardless of which underlying thread - * invoked g_unix_signal_source_new(). - * - * For example, an effective use of this function is to handle `SIGTERM` - * cleanly; flushing any outstanding files, and then calling - * g_main_loop_quit (). It is not safe to do any of this a regular - * UNIX signal handler; your handler may be invoked while malloc() or - * another library function is running, causing reentrancy if you - * attempt to use it from the handler. None of the GLib/GObject API - * is safe against this kind of reentrancy. - * - * The interaction of this source when combined with native UNIX - * functions like sigprocmask() is not defined. - * - * 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. - * - * Returns: A newly created #GSource - * Since: 2.30 - */ - - -/** - * g_unlink: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * - * A wrapper for the POSIX unlink() function. The unlink() function - * deletes a name from the filesystem. If this was the last link to the - * file and no processes have it opened, the diskspace occupied by the - * file is freed. - * - * See your C library manual for more details about unlink(). Note - * that on Windows, it is in general not possible to delete files that - * are open to some process, or mapped into memory. - * - * Returns: 0 if the name was successfully deleted, -1 if an error - * occurred - * Since: 2.6 - */ - - -/** - * g_unsetenv: - * @variable: (type filename): the environment variable to remove, must - * not contain '=' - * - * Removes an environment variable from the environment. - * - * Note that on some systems, when variables are overwritten, the - * memory used for the previous variables and its value isn't reclaimed. - * - * You should be mindful of the fact that environment variable handling - * in UNIX is not thread-safe, and your program may crash if one thread - * calls g_unsetenv() while another thread is calling getenv(). (And note - * that many functions, such as gettext(), call getenv() internally.) This - * function is only safe to use at the very start of your program, before - * creating any other threads (or creating objects that create worker - * threads of their own). - * - * If you need to set up the environment for a child process, you can - * use g_get_environ() to get an environment array, modify that with - * g_environ_setenv() and g_environ_unsetenv(), and then pass that - * array directly to execvpe(), g_spawn_async(), or the like. - * - * Since: 2.4 - */ - - -/** - * g_uri_build: - * @flags: flags describing how to build the #GUri - * @scheme: (not nullable): the URI scheme - * @userinfo: (nullable): the userinfo component, or %NULL - * @host: (nullable): the host component, or %NULL - * @port: the port, or `-1` - * @path: (not nullable): the path component - * @query: (nullable): the query component, or %NULL - * @fragment: (nullable): the fragment, or %NULL - * - * Creates a new #GUri from the given components according to @flags. - * - * See also g_uri_build_with_user(), which allows specifying the - * components of the "userinfo" separately. - * - * Returns: (not nullable) (transfer full): a new #GUri - * Since: 2.66 - */ - - -/** - * g_uri_build_with_user: - * @flags: flags describing how to build the #GUri - * @scheme: (not nullable): the URI scheme - * @user: (nullable): the user component of the userinfo, or %NULL - * @password: (nullable): the password component of the userinfo, or %NULL - * @auth_params: (nullable): the auth params of the userinfo, or %NULL - * @host: (nullable): the host component, or %NULL - * @port: the port, or `-1` - * @path: (not nullable): the path component - * @query: (nullable): the query component, or %NULL - * @fragment: (nullable): the fragment, or %NULL - * - * Creates a new #GUri from the given components according to @flags - * (%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be - * coherent with the passed values, in particular use `%`-encoded values with - * %G_URI_FLAGS_ENCODED. - * - * In contrast to g_uri_build(), this allows specifying the components - * of the ‘userinfo’ field separately. Note that @user must be non-%NULL - * if either @password or @auth_params is non-%NULL. - * - * Returns: (not nullable) (transfer full): a new #GUri - * Since: 2.66 - */ - - -/** - * g_uri_escape_bytes: - * @unescaped: (array length=length): the unescaped input data. - * @length: the length of @unescaped - * @reserved_chars_allowed: (nullable): a string of reserved - * characters that are allowed to be used, or %NULL. - * - * Escapes arbitrary data for use in a URI. - * - * Normally all characters that are not ‘unreserved’ (i.e. ASCII - * alphanumerical characters plus dash, dot, underscore and tilde) are - * escaped. But if you specify characters in @reserved_chars_allowed - * they are not escaped. This is useful for the ‘reserved’ characters - * in the URI specification, since those are allowed unescaped in some - * portions of a URI. - * - * Though technically incorrect, this will also allow escaping nul - * bytes as `%``00`. - * - * Returns: (not nullable) (transfer full): an escaped version of @unescaped. - * The returned string should be freed when no longer needed. - * Since: 2.66 - */ - - -/** - * g_uri_escape_string: - * @unescaped: the unescaped input string. - * @reserved_chars_allowed: (nullable): a string of reserved - * characters that are allowed to be used, or %NULL. - * @allow_utf8: %TRUE if the result can include UTF-8 characters. - * - * Escapes a string for use in a URI. - * - * Normally all characters that are not "unreserved" (i.e. ASCII - * alphanumerical characters plus dash, dot, underscore and tilde) are - * escaped. But if you specify characters in @reserved_chars_allowed - * they are not escaped. This is useful for the "reserved" characters - * in the URI specification, since those are allowed unescaped in some - * portions of a URI. - * - * Returns: (not nullable): an escaped version of @unescaped. The - * returned string should be freed when no longer needed. - * Since: 2.16 - */ - - -/** - * g_uri_get_auth_params: - * @uri: a #GUri - * - * Gets @uri's authentication parameters, which may contain - * `%`-encoding, depending on the flags with which @uri was created. - * (If @uri was not created with %G_URI_FLAGS_HAS_AUTH_PARAMS then this will - * be %NULL.) - * - * Depending on the URI scheme, g_uri_parse_params() may be useful for - * further parsing this information. - * - * Returns: (nullable): @uri's authentication parameters. - * Since: 2.66 - */ - - -/** - * g_uri_get_flags: - * @uri: a #GUri - * - * Gets @uri's flags set upon construction. - * - * Returns: @uri's flags. - * Since: 2.66 - */ - - -/** - * g_uri_get_fragment: - * @uri: a #GUri - * - * Gets @uri's fragment, which may contain `%`-encoding, depending on - * the flags with which @uri was created. - * - * Returns: (nullable): @uri's fragment. - * Since: 2.66 - */ - - -/** - * g_uri_get_host: - * @uri: a #GUri - * - * Gets @uri's host. This will never have `%`-encoded characters, - * unless it is non-UTF-8 (which can only be the case if @uri was - * created with %G_URI_FLAGS_NON_DNS). - * - * If @uri contained an IPv6 address literal, this value will be just - * that address, without the brackets around it that are necessary in - * the string form of the URI. Note that in this case there may also - * be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or - * `fe80::1234%``25em1` if the string is still encoded). - * - * Returns: (nullable): @uri's host. - * Since: 2.66 - */ - - -/** - * g_uri_get_password: - * @uri: a #GUri - * - * Gets @uri's password, which may contain `%`-encoding, depending on - * the flags with which @uri was created. (If @uri was not created - * with %G_URI_FLAGS_HAS_PASSWORD then this will be %NULL.) - * - * Returns: (nullable): @uri's password. - * Since: 2.66 - */ - - -/** - * g_uri_get_path: - * @uri: a #GUri - * - * Gets @uri's path, which may contain `%`-encoding, depending on the - * flags with which @uri was created. - * - * Returns: (not nullable): @uri's path. - * Since: 2.66 - */ - - -/** - * g_uri_get_port: - * @uri: a #GUri - * - * Gets @uri's port. - * - * Returns: @uri's port, or `-1` if no port was specified. - * Since: 2.66 - */ - - -/** - * g_uri_get_query: - * @uri: a #GUri - * - * Gets @uri's query, which may contain `%`-encoding, depending on the - * flags with which @uri was created. - * - * For queries consisting of a series of `name=value` parameters, - * #GUriParamsIter or g_uri_parse_params() may be useful. - * - * Returns: (nullable): @uri's query. - * Since: 2.66 - */ - - -/** - * g_uri_get_scheme: - * @uri: a #GUri - * - * Gets @uri's scheme. Note that this will always be all-lowercase, - * regardless of the string or strings that @uri was created from. - * - * Returns: (not nullable): @uri's scheme. - * Since: 2.66 - */ - - -/** - * g_uri_get_user: - * @uri: a #GUri - * - * Gets the ‘username’ component of @uri's userinfo, which may contain - * `%`-encoding, depending on the flags with which @uri was created. - * If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD or - * %G_URI_FLAGS_HAS_AUTH_PARAMS, this is the same as g_uri_get_userinfo(). - * - * Returns: (nullable): @uri's user. - * Since: 2.66 - */ - - -/** - * g_uri_get_userinfo: - * @uri: a #GUri - * - * Gets @uri's userinfo, which may contain `%`-encoding, depending on - * the flags with which @uri was created. - * - * Returns: (nullable): @uri's userinfo. - * Since: 2.66 - */ - - -/** - * g_uri_is_valid: - * @uri_string: a string containing an absolute URI - * @flags: flags for parsing @uri_string - * @error: #GError for error reporting, or %NULL to ignore. - * - * Parses @uri_string according to @flags, to determine whether it is a valid - * [absolute URI][relative-absolute-uris], i.e. it does not need to be resolved - * relative to another URI using g_uri_parse_relative(). - * - * If it’s not a valid URI, an error is returned explaining how it’s invalid. - * - * See g_uri_split(), and the definition of #GUriFlags, for more - * information on the effect of @flags. - * - * Returns: %TRUE if @uri_string is a valid absolute URI, %FALSE on error. - * Since: 2.66 - */ - - -/** - * g_uri_join: - * @flags: flags describing how to build the URI string - * @scheme: (nullable): the URI scheme, or %NULL - * @userinfo: (nullable): the userinfo component, or %NULL - * @host: (nullable): the host component, or %NULL - * @port: the port, or `-1` - * @path: (not nullable): the path component - * @query: (nullable): the query component, or %NULL - * @fragment: (nullable): the fragment, or %NULL - * - * Joins the given components together according to @flags to create - * an absolute URI string. @path may not be %NULL (though it may be the empty - * string). - * - * When @host is present, @path must either be empty or begin with a slash (`/`) - * character. When @host is not present, @path cannot begin with two slash - * characters (`//`). See - * [RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3). - * - * See also g_uri_join_with_user(), which allows specifying the - * components of the ‘userinfo’ separately. - * - * %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set - * in @flags. - * - * Returns: (not nullable) (transfer full): an absolute URI string - * Since: 2.66 - */ - - -/** - * g_uri_join_with_user: - * @flags: flags describing how to build the URI string - * @scheme: (nullable): the URI scheme, or %NULL - * @user: (nullable): the user component of the userinfo, or %NULL - * @password: (nullable): the password component of the userinfo, or - * %NULL - * @auth_params: (nullable): the auth params of the userinfo, or - * %NULL - * @host: (nullable): the host component, or %NULL - * @port: the port, or `-1` - * @path: (not nullable): the path component - * @query: (nullable): the query component, or %NULL - * @fragment: (nullable): the fragment, or %NULL - * - * Joins the given components together according to @flags to create - * an absolute URI string. @path may not be %NULL (though it may be the empty - * string). - * - * In contrast to g_uri_join(), this allows specifying the components - * of the ‘userinfo’ separately. It otherwise behaves the same. - * - * %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set - * in @flags. - * - * Returns: (not nullable) (transfer full): an absolute URI string - * Since: 2.66 - */ - - -/** - * g_uri_list_extract_uris: - * @uri_list: an URI list - * - * Splits an URI list conforming to the text/uri-list - * mime type defined in RFC 2483 into individual URIs, - * discarding any comments. The URIs are not validated. - * - * Returns: (transfer full): a newly allocated %NULL-terminated list - * of strings holding the individual URIs. The array should be freed - * with g_strfreev(). - * Since: 2.6 - */ - - -/** - * g_uri_params_iter_init: - * @iter: an uninitialized #GUriParamsIter - * @params: a `%`-encoded string containing `attribute=value` - * parameters - * @length: the length of @params, or `-1` if it is nul-terminated - * @separators: the separator byte character set between parameters. (usually - * `&`, but sometimes `;` or both `&;`). Note that this function works on - * bytes not characters, so it can't be used to delimit UTF-8 strings for - * anything but ASCII characters. You may pass an empty set, in which case - * no splitting will occur. - * @flags: flags to modify the way the parameters are handled. - * - * Initializes an attribute/value pair iterator. - * - * The iterator keeps pointers to the @params and @separators arguments, those - * variables must thus outlive the iterator and not be modified during the - * iteration. - * - * If %G_URI_PARAMS_WWW_FORM is passed in @flags, `+` characters in the param - * string will be replaced with spaces in the output. For example, `foo=bar+baz` - * will give attribute `foo` with value `bar baz`. This is commonly used on the - * web (the `https` and `http` schemes only), but is deprecated in favour of - * the equivalent of encoding spaces as `%20`. - * - * Unlike with g_uri_parse_params(), %G_URI_PARAMS_CASE_INSENSITIVE has no - * effect if passed to @flags for g_uri_params_iter_init(). The caller is - * responsible for doing their own case-insensitive comparisons. - * - * |[<!-- language="C" --> - * GUriParamsIter iter; - * GError *error = NULL; - * gchar *unowned_attr, *unowned_value; - * - * g_uri_params_iter_init (&iter, "foo=bar&baz=bar&Foo=frob&baz=bar2", -1, "&", G_URI_PARAMS_NONE); - * while (g_uri_params_iter_next (&iter, &unowned_attr, &unowned_value, &error)) - * { - * g_autofree gchar *attr = g_steal_pointer (&unowned_attr); - * g_autofree gchar *value = g_steal_pointer (&unowned_value); - * // do something with attr and value; this code will be called 4 times - * // for the params string in this example: once with attr=foo and value=bar, - * // then with baz/bar, then Foo/frob, then baz/bar2. - * } - * if (error) - * // handle parsing error - * ]| - * - * Since: 2.66 - */ - - -/** - * g_uri_params_iter_next: - * @iter: an initialized #GUriParamsIter - * @attribute: (out) (nullable) (optional) (transfer full): on return, contains - * the attribute, or %NULL. - * @value: (out) (nullable) (optional) (transfer full): on return, contains - * the value, or %NULL. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Advances @iter and retrieves the next attribute/value. %FALSE is returned if - * an error has occurred (in which case @error is set), or if the end of the - * iteration is reached (in which case @attribute and @value are set to %NULL - * and the iterator becomes invalid). If %TRUE is returned, - * g_uri_params_iter_next() may be called again to receive another - * attribute/value pair. - * - * Note that the same @attribute may be returned multiple times, since URIs - * allow repeated attributes. - * - * Returns: %FALSE if the end of the parameters has been reached or an error was - * encountered. %TRUE otherwise. - * Since: 2.66 - */ - - -/** - * g_uri_parse: - * @uri_string: a string representing an absolute URI - * @flags: flags describing how to parse @uri_string - * @error: #GError for error reporting, or %NULL to ignore. - * - * Parses @uri_string according to @flags. If the result is not a - * valid [absolute URI][relative-absolute-uris], it will be discarded, and an - * error returned. - * - * Returns: (transfer full): a new #GUri, or NULL on error. - * Since: 2.66 - */ - - -/** - * g_uri_parse_params: - * @params: a `%`-encoded string containing `attribute=value` - * parameters - * @length: the length of @params, or `-1` if it is nul-terminated - * @separators: the separator byte character set between parameters. (usually - * `&`, but sometimes `;` or both `&;`). Note that this function works on - * bytes not characters, so it can't be used to delimit UTF-8 strings for - * anything but ASCII characters. You may pass an empty set, in which case - * no splitting will occur. - * @flags: flags to modify the way the parameters are handled. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Many URI schemes include one or more attribute/value pairs as part of the URI - * value. This method can be used to parse them into a hash table. When an - * attribute has multiple occurrences, the last value is the final returned - * value. If you need to handle repeated attributes differently, use - * #GUriParamsIter. - * - * The @params string is assumed to still be `%`-encoded, but the returned - * values will be fully decoded. (Thus it is possible that the returned values - * may contain `=` or @separators, if the value was encoded in the input.) - * Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED - * rules for g_uri_parse(). (However, if @params is the path or query string - * from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and - * %G_URI_FLAGS_ENCODED, then you already know that it does not contain any - * invalid encoding.) - * - * %G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init(). - * - * If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be - * compared case-insensitively, so a params string `attr=123&Attr=456` will only - * return a single attribute–value pair, `Attr=456`. Case will be preserved in - * the returned attributes. - * - * If @params cannot be parsed (for example, it contains two @separators - * characters in a row), then @error is set and %NULL is returned. - * - * Returns: (transfer full) (element-type utf8 utf8): - * A hash table of attribute/value pairs, with both names and values - * fully-decoded; or %NULL on error. - * Since: 2.66 - */ - - -/** - * g_uri_parse_relative: - * @base_uri: (nullable) (transfer none): a base absolute URI - * @uri_ref: a string representing a relative or absolute URI - * @flags: flags describing how to parse @uri_ref - * @error: #GError for error reporting, or %NULL to ignore. - * - * Parses @uri_ref according to @flags and, if it is a - * [relative URI][relative-absolute-uris], resolves it relative to @base_uri. - * If the result is not a valid absolute URI, it will be discarded, and an error - * returned. - * - * Returns: (transfer full): a new #GUri, or NULL on error. - * Since: 2.66 - */ - - -/** - * g_uri_parse_scheme: - * @uri: a valid URI. - * - * Gets the scheme portion of a URI string. - * [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme - * as: - * |[ - * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * ]| - * Common schemes include `file`, `https`, `svn+ssh`, etc. - * - * Returns: (transfer full) (nullable): The ‘scheme’ component of the URI, or - * %NULL on error. The returned string should be freed when no longer needed. - * Since: 2.16 - */ - - -/** - * g_uri_peek_scheme: - * @uri: a valid URI. - * - * Gets the scheme portion of a URI string. - * [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme - * as: - * |[ - * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * ]| - * Common schemes include `file`, `https`, `svn+ssh`, etc. - * - * Unlike g_uri_parse_scheme(), the returned scheme is normalized to - * all-lowercase and does not need to be freed. - * - * Returns: (transfer none) (nullable): The ‘scheme’ component of the URI, or - * %NULL on error. The returned string is normalized to all-lowercase, and - * interned via g_intern_string(), so it does not need to be freed. - * Since: 2.66 - */ - - -/** - * g_uri_ref: (skip) - * @uri: a #GUri - * - * Increments the reference count of @uri by one. - * - * Returns: @uri - * Since: 2.66 - */ - - -/** - * g_uri_resolve_relative: - * @base_uri_string: (nullable): a string representing a base URI - * @uri_ref: a string representing a relative or absolute URI - * @flags: flags describing how to parse @uri_ref - * @error: #GError for error reporting, or %NULL to ignore. - * - * Parses @uri_ref according to @flags and, if it is a - * [relative URI][relative-absolute-uris], resolves it relative to - * @base_uri_string. If the result is not a valid absolute URI, it will be - * discarded, and an error returned. - * - * (If @base_uri_string is %NULL, this just returns @uri_ref, or - * %NULL if @uri_ref is invalid or not absolute.) - * - * Returns: (transfer full): the resolved URI string, - * or NULL on error. - * Since: 2.66 - */ - - -/** - * g_uri_split: - * @uri_ref: a string containing a relative or absolute URI - * @flags: flags for parsing @uri_ref - * @scheme: (out) (nullable) (optional) (transfer full): on return, contains - * the scheme (converted to lowercase), or %NULL - * @userinfo: (out) (nullable) (optional) (transfer full): on return, contains - * the userinfo, or %NULL - * @host: (out) (nullable) (optional) (transfer full): on return, contains the - * host, or %NULL - * @port: (out) (optional) (transfer full): on return, contains the - * port, or `-1` - * @path: (out) (not nullable) (optional) (transfer full): on return, contains the - * path - * @query: (out) (nullable) (optional) (transfer full): on return, contains the - * query, or %NULL - * @fragment: (out) (nullable) (optional) (transfer full): on return, contains - * the fragment, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Parses @uri_ref (which can be an - * [absolute or relative URI][relative-absolute-uris]) according to @flags, and - * returns the pieces. Any component that doesn't appear in @uri_ref will be - * returned as %NULL (but note that all URIs always have a path component, - * though it may be the empty string). - * - * If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in - * @uri_ref will remain encoded in the output strings. (If not, - * then all such characters will be decoded.) Note that decoding will - * only work if the URI components are ASCII or UTF-8, so you will - * need to use %G_URI_FLAGS_ENCODED if they are not. - * - * Note that the %G_URI_FLAGS_HAS_PASSWORD and - * %G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(), - * since it always returns only the full userinfo; use - * g_uri_split_with_user() if you want it split up. - * - * Returns: (skip): %TRUE if @uri_ref parsed successfully, %FALSE - * on error. - * Since: 2.66 - */ - - -/** - * g_uri_split_network: - * @uri_string: a string containing an absolute URI - * @flags: flags for parsing @uri_string - * @scheme: (out) (nullable) (optional) (transfer full): on return, contains - * the scheme (converted to lowercase), or %NULL - * @host: (out) (nullable) (optional) (transfer full): on return, contains the - * host, or %NULL - * @port: (out) (optional) (transfer full): on return, contains the - * port, or `-1` - * @error: #GError for error reporting, or %NULL to ignore. - * - * Parses @uri_string (which must be an [absolute URI][relative-absolute-uris]) - * according to @flags, and returns the pieces relevant to connecting to a host. - * See the documentation for g_uri_split() for more details; this is - * mostly a wrapper around that function with simpler arguments. - * However, it will return an error if @uri_string is a relative URI, - * or does not contain a hostname component. - * - * Returns: (skip): %TRUE if @uri_string parsed successfully, - * %FALSE on error. - * Since: 2.66 - */ - - -/** - * g_uri_split_with_user: - * @uri_ref: a string containing a relative or absolute URI - * @flags: flags for parsing @uri_ref - * @scheme: (out) (nullable) (optional) (transfer full): on return, contains - * the scheme (converted to lowercase), or %NULL - * @user: (out) (nullable) (optional) (transfer full): on return, contains - * the user, or %NULL - * @password: (out) (nullable) (optional) (transfer full): on return, contains - * the password, or %NULL - * @auth_params: (out) (nullable) (optional) (transfer full): on return, contains - * the auth_params, or %NULL - * @host: (out) (nullable) (optional) (transfer full): on return, contains the - * host, or %NULL - * @port: (out) (optional) (transfer full): on return, contains the - * port, or `-1` - * @path: (out) (not nullable) (optional) (transfer full): on return, contains the - * path - * @query: (out) (nullable) (optional) (transfer full): on return, contains the - * query, or %NULL - * @fragment: (out) (nullable) (optional) (transfer full): on return, contains - * the fragment, or %NULL - * @error: #GError for error reporting, or %NULL to ignore. - * - * Parses @uri_ref (which can be an - * [absolute or relative URI][relative-absolute-uris]) according to @flags, and - * returns the pieces. Any component that doesn't appear in @uri_ref will be - * returned as %NULL (but note that all URIs always have a path component, - * though it may be the empty string). - * - * See g_uri_split(), and the definition of #GUriFlags, for more - * information on the effect of @flags. Note that @password will only - * be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and - * @auth_params will only be parsed out if @flags contains - * %G_URI_FLAGS_HAS_AUTH_PARAMS. - * - * Returns: (skip): %TRUE if @uri_ref parsed successfully, %FALSE - * on error. - * Since: 2.66 - */ - - -/** - * g_uri_to_string: - * @uri: a #GUri - * - * Returns a string representing @uri. - * - * This is not guaranteed to return a string which is identical to the - * string that @uri was parsed from. However, if the source URI was - * syntactically correct (according to RFC 3986), and it was parsed - * with %G_URI_FLAGS_ENCODED, then g_uri_to_string() is guaranteed to return - * a string which is at least semantically equivalent to the source - * URI (according to RFC 3986). - * - * If @uri might contain sensitive details, such as authentication parameters, - * or private data in its query string, and the returned string is going to be - * logged, then consider using g_uri_to_string_partial() to redact parts. - * - * Returns: (not nullable) (transfer full): a string representing @uri, - * which the caller must free. - * Since: 2.66 - */ - - -/** - * g_uri_to_string_partial: - * @uri: a #GUri - * @flags: flags describing what parts of @uri to hide - * - * Returns a string representing @uri, subject to the options in - * @flags. See g_uri_to_string() and #GUriHideFlags for more details. - * - * Returns: (not nullable) (transfer full): a string representing - * @uri, which the caller must free. - * Since: 2.66 - */ - - -/** - * g_uri_unescape_bytes: - * @escaped_string: A URI-escaped string - * @length: the length (in bytes) of @escaped_string to escape, or `-1` if it - * is nul-terminated. - * @illegal_characters: (nullable): a string of illegal characters - * not to be allowed, or %NULL. - * @error: #GError for error reporting, or %NULL to ignore. - * - * Unescapes a segment of an escaped string as binary data. - * - * Note that in contrast to g_uri_unescape_string(), this does allow - * nul bytes to appear in the output. - * - * If any of the characters in @illegal_characters appears as an escaped - * character in @escaped_string, then that is an error and %NULL will be - * returned. This is useful if you want to avoid for instance having a slash - * being expanded in an escaped path element, which might confuse pathname - * handling. - * - * Returns: (transfer full): an unescaped version of @escaped_string - * or %NULL on error (if decoding failed, using %G_URI_ERROR_FAILED error - * code). The returned #GBytes should be unreffed when no longer needed. - * Since: 2.66 - */ - - -/** - * g_uri_unescape_segment: - * @escaped_string: (nullable): A string, may be %NULL - * @escaped_string_end: (nullable): Pointer to end of @escaped_string, - * may be %NULL - * @illegal_characters: (nullable): An optional string of illegal - * characters not to be allowed, may be %NULL - * - * Unescapes a segment of an escaped string. - * - * If any of the characters in @illegal_characters or the NUL - * character appears as an escaped character in @escaped_string, then - * that is an error and %NULL will be returned. This is useful if you - * want to avoid for instance having a slash being expanded in an - * escaped path element, which might confuse pathname handling. - * - * Note: `NUL` byte is not accepted in the output, in contrast to - * g_uri_unescape_bytes(). - * - * Returns: (nullable): an unescaped version of @escaped_string, - * or %NULL on error. The returned string should be freed when no longer - * needed. As a special case if %NULL is given for @escaped_string, this - * function will return %NULL. - * Since: 2.16 - */ - - -/** - * g_uri_unescape_string: - * @escaped_string: an escaped string to be unescaped. - * @illegal_characters: (nullable): a string of illegal characters - * not to be allowed, or %NULL. - * - * Unescapes a whole escaped string. - * - * If any of the characters in @illegal_characters or the NUL - * character appears as an escaped character in @escaped_string, then - * that is an error and %NULL will be returned. This is useful if you - * want to avoid for instance having a slash being expanded in an - * escaped path element, which might confuse pathname handling. - * - * Returns: (nullable): an unescaped version of @escaped_string. - * The returned string should be freed when no longer needed. - * Since: 2.16 - */ - - -/** - * g_uri_unref: (skip) - * @uri: a #GUri - * - * Atomically decrements the reference count of @uri by one. - * - * When the reference count reaches zero, the resources allocated by - * @uri are freed - * - * Since: 2.66 - */ - - -/** - * g_usleep: - * @microseconds: number of microseconds to pause - * - * Pauses the current thread for the given number of microseconds. - * - * There are 1 million microseconds per second (represented by the - * #G_USEC_PER_SEC macro). g_usleep() may have limited precision, - * depending on hardware and operating system; don't rely on the exact - * length of the sleep. - */ - - -/** - * g_utf16_to_ucs4: - * @str: a UTF-16 encoded string - * @len: the maximum length (number of #gunichar2) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (out) (optional): location to store number of - * words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - * be returned in case @str contains a trailing partial character. If - * an error occurs then the index of the invalid input is stored here. - * @items_written: (out) (optional): location to store number - * of characters written, or %NULL. The value stored here does not include - * the trailing 0 character. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. - * - * Convert a string from UTF-16 to UCS-4. The result will be - * nul-terminated. - * - * Returns: (transfer full): a pointer to a newly allocated UCS-4 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. - */ - - -/** - * g_utf16_to_utf8: - * @str: a UTF-16 encoded string - * @len: the maximum length (number of #gunichar2) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (out) (optional): location to store number of - * words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - * be returned in case @str contains a trailing partial character. If - * an error occurs then the index of the invalid input is stored here. - * @items_written: (out) (optional): location to store number - * of bytes written, or %NULL. The value stored here does not include the - * trailing 0 byte. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. - * - * Convert a string from UTF-16 to UTF-8. The result will be - * terminated with a 0 byte. - * - * Note that the input is expected to be already in native endianness, - * an initial byte-order-mark character is not handled specially. - * g_convert() can be used to convert a byte buffer of UTF-16 data of - * ambiguous endianness. - * - * Further note that this function does not validate the result - * string; it may e.g. include embedded NUL characters. The only - * validation done by this function is to ensure that the input can - * be correctly interpreted as UTF-16, i.e. it doesn't contain - * unpaired surrogates or partial character sequences. - * - * Returns: (transfer full): a pointer to a newly allocated UTF-8 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. - */ - - -/** - * g_utf8_casefold: - * @str: a UTF-8 encoded string - * @len: length of @str, in bytes, or -1 if @str is nul-terminated. - * - * Converts a string into a form that is independent of case. The - * result will not correspond to any particular case, but can be - * compared for equality or ordered with the results of calling - * g_utf8_casefold() on other strings. - * - * Note that calling g_utf8_casefold() followed by g_utf8_collate() is - * only an approximation to the correct linguistic case insensitive - * ordering, though it is a fairly good one. Getting this exactly - * right would require a more sophisticated collation function that - * takes case sensitivity into account. GLib does not currently - * provide such a function. - * - * Returns: a newly allocated string, that is a - * case independent form of @str. - */ - - -/** - * g_utf8_collate: - * @str1: a UTF-8 encoded string - * @str2: a UTF-8 encoded string - * - * Compares two strings for ordering using the linguistically - * correct rules for the [current locale][setlocale]. - * When sorting a large number of strings, it will be significantly - * faster to obtain collation keys with g_utf8_collate_key() and - * compare the keys with strcmp() when sorting instead of sorting - * the original strings. - * - * Returns: < 0 if @str1 compares before @str2, - * 0 if they compare equal, > 0 if @str1 compares after @str2. - */ - - -/** - * g_utf8_collate_key: - * @str: a UTF-8 encoded string. - * @len: length of @str, in bytes, or -1 if @str is nul-terminated. - * - * Converts a string into a collation key that can be compared - * with other collation keys produced by the same function using - * strcmp(). - * - * The results of comparing the collation keys of two strings - * with strcmp() will always be the same as comparing the two - * original keys with g_utf8_collate(). - * - * Note that this function depends on the [current locale][setlocale]. - * - * Returns: a newly allocated string. This string should - * be freed with g_free() when you are done with it. - */ - - -/** - * g_utf8_collate_key_for_filename: - * @str: a UTF-8 encoded string. - * @len: length of @str, in bytes, or -1 if @str is nul-terminated. - * - * Converts a string into a collation key that can be compared - * with other collation keys produced by the same function using strcmp(). - * - * In order to sort filenames correctly, this function treats the dot '.' - * as a special case. Most dictionary orderings seem to consider it - * insignificant, thus producing the ordering "event.c" "eventgenerator.c" - * "event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we - * would like to treat numbers intelligently so that "file1" "file10" "file5" - * is sorted as "file1" "file5" "file10". - * - * Note that this function depends on the [current locale][setlocale]. - * - * Returns: a newly allocated string. This string should - * be freed with g_free() when you are done with it. - * Since: 2.8 - */ - - -/** - * g_utf8_find_next_char: - * @p: a pointer to a position within a UTF-8 encoded string - * @end: (nullable): a pointer to the byte following the end of the string, - * or %NULL to indicate that the string is nul-terminated - * - * Finds the start of the next UTF-8 character in the string after @p. - * - * @p does not have to be at the beginning of a UTF-8 character. No check - * is made to see if the character found is actually valid other than - * it starts with an appropriate byte. - * - * If @end is %NULL, the return value will never be %NULL: if the end of the - * string is reached, a pointer to the terminating nul byte is returned. If - * @end is non-%NULL, the return value will be %NULL if the end of the string - * is reached. - * - * Returns: (transfer none) (nullable): a pointer to the found character or %NULL if @end is - * set and is reached - */ - - -/** - * g_utf8_find_prev_char: - * @str: pointer to the beginning of a UTF-8 encoded string - * @p: pointer to some position within @str - * - * Given a position @p with a UTF-8 encoded string @str, find the start - * of the previous UTF-8 character starting before @p. Returns %NULL if no - * UTF-8 characters are present in @str before @p. - * - * @p does not have to be at the beginning of a UTF-8 character. No check - * is made to see if the character found is actually valid other than - * it starts with an appropriate byte. - * - * Returns: (transfer none) (nullable): a pointer to the found character or %NULL. - */ - - -/** - * g_utf8_get_char: - * @p: a pointer to Unicode character encoded as UTF-8 - * - * Converts a sequence of bytes encoded as UTF-8 to a Unicode character. - * - * If @p does not point to a valid UTF-8 encoded character, results - * are undefined. If you are not sure that the bytes are complete - * valid Unicode characters, you should use g_utf8_get_char_validated() - * instead. - * - * Returns: the resulting character - */ - - -/** - * g_utf8_get_char_validated: - * @p: a pointer to Unicode character encoded as UTF-8 - * @max_len: the maximum number of bytes to read, or -1 if @p is nul-terminated - * - * Convert a sequence of bytes encoded as UTF-8 to a Unicode character. - * This function checks for incomplete characters, for invalid characters - * such as characters that are out of the range of Unicode, and for - * overlong encodings of valid characters. - * - * Note that g_utf8_get_char_validated() returns (gunichar)-2 if - * @max_len is positive and any of the bytes in the first UTF-8 character - * sequence are nul. - * - * Returns: the resulting character. If @p points to a partial - * sequence at the end of a string that could begin a valid - * character (or if @max_len is zero), returns (gunichar)-2; - * otherwise, if @p does not point to a valid UTF-8 encoded - * Unicode character, returns (gunichar)-1. - */ - - -/** - * g_utf8_make_valid: - * @str: string to coerce into UTF-8 - * @len: the maximum length of @str to use, in bytes. If @len < 0, - * then the string is nul-terminated. - * - * If the provided string is valid UTF-8, return a copy of it. If not, - * return a copy in which bytes that could not be interpreted as valid Unicode - * are replaced with the Unicode replacement character (U+FFFD). - * - * For example, this is an appropriate function to use if you have received - * a string that was incorrectly declared to be UTF-8, and you need a valid - * UTF-8 version of it that can be logged or displayed to the user, with the - * assumption that it is close enough to ASCII or UTF-8 to be mostly - * readable as-is. - * - * Returns: (transfer full): a valid UTF-8 string whose content resembles @str - * Since: 2.52 - */ - - -/** - * g_utf8_normalize: - * @str: a UTF-8 encoded string. - * @len: length of @str, in bytes, or -1 if @str is nul-terminated. - * @mode: the type of normalization to perform. - * - * Converts a string into canonical form, standardizing - * such issues as whether a character with an accent - * is represented as a base character and combining - * accent or as a single precomposed character. The - * string has to be valid UTF-8, otherwise %NULL is - * returned. You should generally call g_utf8_normalize() - * before comparing two Unicode strings. - * - * The normalization mode %G_NORMALIZE_DEFAULT only - * standardizes differences that do not affect the - * text content, such as the above-mentioned accent - * representation. %G_NORMALIZE_ALL also standardizes - * the "compatibility" characters in Unicode, such - * as SUPERSCRIPT THREE to the standard forms - * (in this case DIGIT THREE). Formatting information - * may be lost but for most text operations such - * characters should be considered the same. - * - * %G_NORMALIZE_DEFAULT_COMPOSE and %G_NORMALIZE_ALL_COMPOSE - * are like %G_NORMALIZE_DEFAULT and %G_NORMALIZE_ALL, - * but returned a result with composed forms rather - * than a maximally decomposed form. This is often - * useful if you intend to convert the string to - * a legacy encoding or pass it to a system with - * less capable Unicode handling. - * - * Returns: (nullable): a newly allocated string, that - * is the normalized form of @str, or %NULL if @str - * is not valid UTF-8. - */ - - -/** - * g_utf8_offset_to_pointer: - * @str: a UTF-8 encoded string - * @offset: a character offset within @str - * - * Converts from an integer character offset to a pointer to a position - * within the string. - * - * Since 2.10, this function allows to pass a negative @offset to - * step backwards. It is usually worth stepping backwards from the end - * instead of forwards if @offset is in the last fourth of the string, - * since moving forward is about 3 times faster than moving backward. - * - * Note that this function doesn't abort when reaching the end of @str. - * Therefore you should be sure that @offset is within string boundaries - * before calling that function. Call g_utf8_strlen() when unsure. - * This limitation exists as this function is called frequently during - * text rendering and therefore has to be as fast as possible. - * - * Returns: (transfer none): the resulting pointer - */ - - -/** - * g_utf8_pointer_to_offset: - * @str: a UTF-8 encoded string - * @pos: a pointer to a position within @str - * - * Converts from a pointer to position within a string to an integer - * character offset. - * - * Since 2.10, this function allows @pos to be before @str, and returns - * a negative offset in this case. - * - * Returns: the resulting character offset - */ - - -/** - * g_utf8_prev_char: - * @p: a pointer to a position within a UTF-8 encoded string - * - * Finds the previous UTF-8 character in the string before @p. - * - * @p does not have to be at the beginning of a UTF-8 character. No check - * is made to see if the character found is actually valid other than - * it starts with an appropriate byte. If @p might be the first - * character of the string, you must use g_utf8_find_prev_char() instead. - * - * Returns: (transfer none) (not nullable): a pointer to the found character - */ - - -/** - * g_utf8_strchr: - * @p: a nul-terminated UTF-8 encoded string - * @len: the maximum length of @p - * @c: a Unicode character - * - * Finds the leftmost occurrence of the given Unicode character - * in a UTF-8 encoded string, while limiting the search to @len bytes. - * If @len is -1, allow unbounded search. - * - * Returns: (transfer none) (nullable): %NULL if the string does not contain the character, - * otherwise, a pointer to the start of the leftmost occurrence - * of the character in the string. - */ - - -/** - * g_utf8_strdown: - * @str: a UTF-8 encoded string - * @len: length of @str, in bytes, or -1 if @str is nul-terminated. - * - * Converts all Unicode characters in the string that have a case - * to lowercase. The exact manner that this is done depends - * on the current locale, and may result in the number of - * characters in the string changing. - * - * Returns: a newly allocated string, with all characters - * converted to lowercase. - */ - - -/** - * g_utf8_strlen: - * @p: pointer to the start of a UTF-8 encoded string - * @max: the maximum number of bytes to examine. If @max - * is less than 0, then the string is assumed to be - * nul-terminated. If @max is 0, @p will not be examined and - * may be %NULL. If @max is greater than 0, up to @max - * bytes are examined - * - * Computes the length of the string in characters, not including - * the terminating nul character. If the @max'th byte falls in the - * middle of a character, the last (partial) character is not counted. - * - * Returns: the length of the string in characters - */ - - -/** - * g_utf8_strncpy: - * @dest: (transfer none): buffer to fill with characters from @src - * @src: UTF-8 encoded string - * @n: character count - * - * Like the standard C strncpy() function, but copies a given number - * of characters instead of a given number of bytes. The @src string - * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all - * text before trying to use UTF-8 utility functions with it.) - * - * Note you must ensure @dest is at least 4 * @n to fit the - * largest possible UTF-8 characters - * - * Returns: (transfer none): @dest - */ - - -/** - * g_utf8_strrchr: - * @p: a nul-terminated UTF-8 encoded string - * @len: the maximum length of @p - * @c: a Unicode character - * - * Find the rightmost occurrence of the given Unicode character - * in a UTF-8 encoded string, while limiting the search to @len bytes. - * If @len is -1, allow unbounded search. - * - * Returns: (transfer none) (nullable): %NULL if the string does not contain the character, - * otherwise, a pointer to the start of the rightmost occurrence - * of the character in the string. - */ - - -/** - * g_utf8_strreverse: - * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, - * then the string is nul-terminated. - * - * Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. - * (Use g_utf8_validate() on all text before trying to use UTF-8 - * utility functions with it.) - * - * This function is intended for programmatic uses of reversed strings. - * It pays no attention to decomposed characters, combining marks, byte - * order marks, directional indicators (LRM, LRO, etc) and similar - * characters which might need special handling when reversing a string - * for display purposes. - * - * Note that unlike g_strreverse(), this function returns - * newly-allocated memory, which should be freed with g_free() when - * no longer needed. - * - * Returns: (transfer full): a newly-allocated string which is the reverse of @str - * Since: 2.2 - */ - - -/** - * g_utf8_strup: - * @str: a UTF-8 encoded string - * @len: length of @str, in bytes, or -1 if @str is nul-terminated. - * - * Converts all Unicode characters in the string that have a case - * to uppercase. The exact manner that this is done depends - * on the current locale, and may result in the number of - * characters in the string increasing. (For instance, the - * German ess-zet will be changed to SS.) - * - * Returns: a newly allocated string, with all characters - * converted to uppercase. - */ - - -/** - * g_utf8_substring: - * @str: a UTF-8 encoded string - * @start_pos: a character offset within @str - * @end_pos: another character offset within @str - * - * Copies a substring out of a UTF-8 encoded string. - * The substring will contain @end_pos - @start_pos characters. - * - * Returns: (transfer full): a newly allocated copy of the requested - * substring. Free with g_free() when no longer needed. - * Since: 2.30 - */ - - -/** - * g_utf8_to_ucs4: - * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, - * then the string is nul-terminated. - * @items_read: (out) (optional): location to store number of - * bytes read, or %NULL. - * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be - * returned in case @str contains a trailing partial - * character. If an error occurs then the index of the - * invalid input is stored here. - * @items_written: (out) (optional): location to store number - * of characters written or %NULL. The value here stored does not include - * the trailing 0 character. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. - * - * Convert a string from UTF-8 to a 32-bit fixed width - * representation as UCS-4. A trailing 0 character will be added to the - * string after the converted text. - * - * Returns: (transfer full): a pointer to a newly allocated UCS-4 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. - */ - - -/** - * g_utf8_to_ucs4_fast: - * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, - * then the string is nul-terminated. - * @items_written: (out) (optional): location to store the - * number of characters in the result, or %NULL. - * - * Convert a string from UTF-8 to a 32-bit fixed width - * representation as UCS-4, assuming valid UTF-8 input. - * This function is roughly twice as fast as g_utf8_to_ucs4() - * but does no error checking on the input. A trailing 0 character - * will be added to the string after the converted text. - * - * Returns: (transfer full): a pointer to a newly allocated UCS-4 string. - * This value must be freed with g_free(). - */ - - -/** - * g_utf8_to_utf16: - * @str: a UTF-8 encoded string - * @len: the maximum length (number of bytes) of @str to use. - * If @len < 0, then the string is nul-terminated. - * @items_read: (out) (optional): location to store number of - * bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - * be returned in case @str contains a trailing partial character. If - * an error occurs then the index of the invalid input is stored here. - * @items_written: (out) (optional): location to store number - * of #gunichar2 written, or %NULL. The value stored here does not include - * the trailing 0. - * @error: location to store the error occurring, or %NULL to ignore - * errors. Any of the errors in #GConvertError other than - * %G_CONVERT_ERROR_NO_CONVERSION may occur. - * - * Convert a string from UTF-8 to UTF-16. A 0 character will be - * added to the result after the converted text. - * - * Returns: (transfer full): a pointer to a newly allocated UTF-16 string. - * This value must be freed with g_free(). If an error occurs, - * %NULL will be returned and @error set. - */ - - -/** - * g_utf8_validate: - * @str: (array length=max_len) (element-type guint8): a pointer to character data - * @max_len: max bytes to validate, or -1 to go until NUL - * @end: (out) (optional) (transfer none): return location for end of valid data - * - * Validates UTF-8 encoded text. @str is the text to validate; - * if @str is nul-terminated, then @max_len can be -1, otherwise - * @max_len should be the number of bytes to validate. - * If @end is non-%NULL, then the end of the valid range - * will be stored there (i.e. the start of the first invalid - * character if some bytes were invalid, or the end of the text - * being validated otherwise). - * - * Note that g_utf8_validate() returns %FALSE if @max_len is - * positive and any of the @max_len bytes are nul. - * - * Returns %TRUE if all of @str was valid. Many GLib and GTK+ - * routines require valid UTF-8 as input; so data read from a file - * or the network should be checked with g_utf8_validate() before - * doing anything else with it. - * - * Returns: %TRUE if the text was valid UTF-8 - */ - - -/** - * g_utf8_validate_len: - * @str: (array length=max_len) (element-type guint8): a pointer to character data - * @max_len: max bytes to validate - * @end: (out) (optional) (transfer none): return location for end of valid data - * - * Validates UTF-8 encoded text. - * - * As with g_utf8_validate(), but @max_len must be set, and hence this function - * will always return %FALSE if any of the bytes of @str are nul. - * - * Returns: %TRUE if the text was valid UTF-8 - * Since: 2.60 - */ - - -/** - * g_utime: - * @filename: (type filename): a pathname in the GLib file name encoding - * (UTF-8 on Windows) - * @utb: a pointer to a struct utimbuf. - * - * A wrapper for the POSIX utime() function. The utime() function - * sets the access and modification timestamps of a file. - * - * See your C library manual for more details about how utime() works - * on your system. - * - * Returns: 0 if the operation was successful, -1 if an error occurred - * Since: 2.18 - */ - - -/** - * g_uuid_string_is_valid: - * @str: a string representing a UUID - * - * Parses the string @str and verify if it is a UUID. - * - * The function accepts the following syntax: - * - * - simple forms (e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`) - * - * Note that hyphens are required within the UUID string itself, - * as per the aforementioned RFC. - * - * Returns: %TRUE if @str is a valid UUID, %FALSE otherwise. - * Since: 2.52 - */ - - -/** - * g_uuid_string_random: - * - * Generates a random UUID (RFC 4122 version 4) as a string. It has the same - * randomness guarantees as #GRand, so must not be used for cryptographic - * purposes such as key generation, nonces, salts or one-time pads. - * - * Returns: (transfer full): A string that should be freed with g_free(). - * Since: 2.52 - */ - - -/** - * g_variant_builder_add: (skip) - * @builder: a #GVariantBuilder - * @format_string: a #GVariant varargs format string - * @...: arguments, as per @format_string - * - * Adds to a #GVariantBuilder. - * - * This call is a convenience wrapper that is exactly equivalent to - * calling g_variant_new() followed by g_variant_builder_add_value(). - * - * Note that the arguments must be of the correct width for their types - * specified in @format_string. This can be achieved by casting them. See - * the [GVariant varargs documentation][gvariant-varargs]. - * - * This function might be used as follows: - * - * |[<!-- language="C" --> - * GVariant * - * make_pointless_dictionary (void) - * { - * GVariantBuilder builder; - * int i; - * - * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); - * for (i = 0; i < 16; i++) - * { - * gchar buf[3]; - * - * sprintf (buf, "%d", i); - * g_variant_builder_add (&builder, "{is}", i, buf); - * } - * - * return g_variant_builder_end (&builder); - * } - * ]| - * - * Since: 2.24 - */ - - -/** - * g_variant_builder_add_parsed: - * @builder: a #GVariantBuilder - * @format: a text format #GVariant - * @...: arguments as per @format - * - * Adds to a #GVariantBuilder. - * - * This call is a convenience wrapper that is exactly equivalent to - * calling g_variant_new_parsed() followed by - * g_variant_builder_add_value(). - * - * Note that the arguments must be of the correct width for their types - * specified in @format_string. This can be achieved by casting them. See - * the [GVariant varargs documentation][gvariant-varargs]. - * - * This function might be used as follows: - * - * |[<!-- language="C" --> - * GVariant * - * make_pointless_dictionary (void) - * { - * GVariantBuilder builder; - * int i; - * - * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); - * g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600); - * g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo"); - * g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}"); - * return g_variant_builder_end (&builder); - * } - * ]| - * - * Since: 2.26 - */ - - -/** - * g_variant_builder_add_value: - * @builder: a #GVariantBuilder - * @value: a #GVariant - * - * Adds @value to @builder. - * - * It is an error to call this function in any way that would create an - * inconsistent value to be constructed. Some examples of this are - * putting different types of items into an array, putting the wrong - * types or number of items in a tuple, putting more than one value into - * a variant, etc. - * - * If @value is a floating reference (see g_variant_ref_sink()), - * the @builder instance takes ownership of @value. - * - * Since: 2.24 - */ - - -/** - * g_variant_builder_clear: (skip) - * @builder: a #GVariantBuilder - * - * Releases all memory associated with a #GVariantBuilder without - * freeing the #GVariantBuilder structure itself. - * - * It typically only makes sense to do this on a stack-allocated - * #GVariantBuilder if you want to abort building the value part-way - * through. This function need not be called if you call - * g_variant_builder_end() and it also doesn't need to be called on - * builders allocated with g_variant_builder_new() (see - * g_variant_builder_unref() for that). - * - * This function leaves the #GVariantBuilder structure set to all-zeros. - * It is valid to call this function on either an initialised - * #GVariantBuilder or one that is set to all-zeros but it is not valid - * to call this function on uninitialised memory. - * - * Since: 2.24 - */ - - -/** - * g_variant_builder_close: - * @builder: a #GVariantBuilder - * - * Closes the subcontainer inside the given @builder that was opened by - * the most recent call to g_variant_builder_open(). - * - * It is an error to call this function in any way that would create an - * inconsistent value to be constructed (ie: too few values added to the - * subcontainer). - * - * Since: 2.24 - */ - - -/** - * g_variant_builder_end: - * @builder: a #GVariantBuilder - * - * Ends the builder process and returns the constructed value. - * - * It is not permissible to use @builder in any way after this call - * except for reference counting operations (in the case of a - * heap-allocated #GVariantBuilder) or by reinitialising it with - * g_variant_builder_init() (in the case of stack-allocated). This - * means that for the stack-allocated builders there is no need to - * call g_variant_builder_clear() after the call to - * g_variant_builder_end(). - * - * It is an error to call this function in any way that would create an - * inconsistent value to be constructed (ie: insufficient number of - * items added to a container with a specific number of children - * required). It is also an error to call this function if the builder - * was created with an indefinite array or maybe type and no children - * have been added; in this case it is impossible to infer the type of - * the empty array. - * - * Returns: (transfer none): a new, floating, #GVariant - * Since: 2.24 - */ - - -/** - * g_variant_builder_init: (skip) - * @builder: a #GVariantBuilder - * @type: a container type - * - * Initialises a #GVariantBuilder structure. - * - * @type must be non-%NULL. It specifies the type of container to - * construct. It can be an indefinite type such as - * %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)". - * Maybe, array, tuple, dictionary entry and variant-typed values may be - * constructed. - * - * After the builder is initialised, values are added using - * g_variant_builder_add_value() or g_variant_builder_add(). - * - * After all the child values are added, g_variant_builder_end() frees - * the memory associated with the builder and returns the #GVariant that - * was created. - * - * This function completely ignores the previous contents of @builder. - * On one hand this means that it is valid to pass in completely - * uninitialised memory. On the other hand, this means that if you are - * initialising over top of an existing #GVariantBuilder you need to - * first call g_variant_builder_clear() in order to avoid leaking - * memory. - * - * You must not call g_variant_builder_ref() or - * g_variant_builder_unref() on a #GVariantBuilder that was initialised - * with this function. If you ever pass a reference to a - * #GVariantBuilder outside of the control of your own code then you - * should assume that the person receiving that reference may try to use - * reference counting; you should use g_variant_builder_new() instead of - * this function. - * - * Since: 2.24 - */ - - -/** - * g_variant_builder_new: - * @type: a container type - * - * Allocates and initialises a new #GVariantBuilder. - * - * You should call g_variant_builder_unref() on the return value when it - * is no longer needed. The memory will not be automatically freed by - * any other call. - * - * In most cases it is easier to place a #GVariantBuilder directly on - * the stack of the calling function and initialise it with - * g_variant_builder_init(). - * - * Returns: (transfer full): a #GVariantBuilder - * Since: 2.24 - */ - - -/** - * g_variant_builder_open: - * @builder: a #GVariantBuilder - * @type: the #GVariantType of the container - * - * Opens a subcontainer inside the given @builder. When done adding - * items to the subcontainer, g_variant_builder_close() must be called. @type - * is the type of the container: so to build a tuple of several values, @type - * must include the tuple itself. - * - * It is an error to call this function in any way that would cause an - * inconsistent value to be constructed (ie: adding too many values or - * a value of an incorrect type). - * - * Example of building a nested variant: - * |[<!-- language="C" --> - * GVariantBuilder builder; - * guint32 some_number = get_number (); - * g_autoptr (GHashTable) some_dict = get_dict (); - * GHashTableIter iter; - * const gchar *key; - * const GVariant *value; - * g_autoptr (GVariant) output = NULL; - * - * g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})")); - * g_variant_builder_add (&builder, "u", some_number); - * g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}")); - * - * g_hash_table_iter_init (&iter, some_dict); - * while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value)) - * { - * g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}")); - * g_variant_builder_add (&builder, "s", key); - * g_variant_builder_add (&builder, "v", value); - * g_variant_builder_close (&builder); - * } - * - * g_variant_builder_close (&builder); - * - * output = g_variant_builder_end (&builder); - * ]| - * - * Since: 2.24 - */ - - -/** - * g_variant_builder_ref: - * @builder: a #GVariantBuilder allocated by g_variant_builder_new() - * - * Increases the reference count on @builder. - * - * Don't call this on stack-allocated #GVariantBuilder instances or bad - * things will happen. - * - * Returns: (transfer full): a new reference to @builder - * Since: 2.24 - */ - - -/** - * g_variant_builder_unref: - * @builder: (transfer full): a #GVariantBuilder allocated by g_variant_builder_new() - * - * Decreases the reference count on @builder. - * - * In the event that there are no more references, releases all memory - * associated with the #GVariantBuilder. - * - * Don't call this on stack-allocated #GVariantBuilder instances or bad - * things will happen. - * - * Since: 2.24 - */ - - -/** - * g_variant_byteswap: - * @value: a #GVariant - * - * Performs a byteswapping operation on the contents of @value. The - * result is that all multi-byte numeric data contained in @value is - * byteswapped. That includes 16, 32, and 64bit signed and unsigned - * integers as well as file handles and double precision floating point - * values. - * - * This function is an identity mapping on any value that does not - * contain multi-byte numeric data. That include strings, booleans, - * bytes and containers containing only these things (recursively). - * - * The returned value is always in normal form and is marked as trusted. - * - * Returns: (transfer full): the byteswapped form of @value - * Since: 2.24 - */ - - -/** - * g_variant_check_format_string: - * @value: a #GVariant - * @format_string: a valid #GVariant format string - * @copy_only: %TRUE to ensure the format string makes deep copies - * - * Checks if calling g_variant_get() with @format_string on @value would - * be valid from a type-compatibility standpoint. @format_string is - * assumed to be a valid format string (from a syntactic standpoint). - * - * If @copy_only is %TRUE then this function additionally checks that it - * would be safe to call g_variant_unref() on @value immediately after - * the call to g_variant_get() without invalidating the result. This is - * only possible if deep copies are made (ie: there are no pointers to - * the data inside of the soon-to-be-freed #GVariant instance). If this - * check fails then a g_critical() is printed and %FALSE is returned. - * - * This function is meant to be used by functions that wish to provide - * varargs accessors to #GVariant values of uncertain values (eg: - * g_variant_lookup() or g_menu_model_get_item_attribute()). - * - * Returns: %TRUE if @format_string is safe to use - * Since: 2.34 - */ - - -/** - * g_variant_classify: - * @value: a #GVariant - * - * Classifies @value according to its top-level type. - * - * Returns: the #GVariantClass of @value - * Since: 2.24 - */ - - -/** - * g_variant_compare: - * @one: (type GVariant): a basic-typed #GVariant instance - * @two: (type GVariant): a #GVariant instance of the same type - * - * Compares @one and @two. - * - * The types of @one and @two are #gconstpointer only to allow use of - * this function with #GTree, #GPtrArray, etc. They must each be a - * #GVariant. - * - * Comparison is only defined for basic types (ie: booleans, numbers, - * strings). For booleans, %FALSE is less than %TRUE. Numbers are - * ordered in the usual way. Strings are in ASCII lexographical order. - * - * It is a programmer error to attempt to compare container values or - * two values that have types that are not exactly equal. For example, - * you cannot compare a 32-bit signed integer with a 32-bit unsigned - * integer. Also note that this function is not particularly - * well-behaved when it comes to comparison of doubles; in particular, - * the handling of incomparable values (ie: NaN) is undefined. - * - * If you only require an equality comparison, g_variant_equal() is more - * general. - * - * Returns: negative value if a < b; - * zero if a = b; - * positive value if a > b. - * Since: 2.26 - */ - - -/** - * g_variant_dict_clear: - * @dict: a #GVariantDict - * - * Releases all memory associated with a #GVariantDict without freeing - * the #GVariantDict structure itself. - * - * It typically only makes sense to do this on a stack-allocated - * #GVariantDict if you want to abort building the value part-way - * through. This function need not be called if you call - * g_variant_dict_end() and it also doesn't need to be called on dicts - * allocated with g_variant_dict_new (see g_variant_dict_unref() for - * that). - * - * It is valid to call this function on either an initialised - * #GVariantDict or one that was previously cleared by an earlier call - * to g_variant_dict_clear() but it is not valid to call this function - * on uninitialised memory. - * - * Since: 2.40 - */ - - -/** - * g_variant_dict_contains: - * @dict: a #GVariantDict - * @key: the key to look up in the dictionary - * - * Checks if @key exists in @dict. - * - * Returns: %TRUE if @key is in @dict - * Since: 2.40 - */ - - -/** - * g_variant_dict_end: - * @dict: a #GVariantDict - * - * Returns the current value of @dict as a #GVariant of type - * %G_VARIANT_TYPE_VARDICT, clearing it in the process. - * - * It is not permissible to use @dict in any way after this call except - * for reference counting operations (in the case of a heap-allocated - * #GVariantDict) or by reinitialising it with g_variant_dict_init() (in - * the case of stack-allocated). - * - * Returns: (transfer none): a new, floating, #GVariant - * Since: 2.40 - */ - - -/** - * g_variant_dict_init: (skip) - * @dict: a #GVariantDict - * @from_asv: (nullable): the initial value for @dict - * - * Initialises a #GVariantDict structure. - * - * If @from_asv is given, it is used to initialise the dictionary. - * - * This function completely ignores the previous contents of @dict. On - * one hand this means that it is valid to pass in completely - * uninitialised memory. On the other hand, this means that if you are - * initialising over top of an existing #GVariantDict you need to first - * call g_variant_dict_clear() in order to avoid leaking memory. - * - * You must not call g_variant_dict_ref() or g_variant_dict_unref() on a - * #GVariantDict that was initialised with this function. If you ever - * pass a reference to a #GVariantDict outside of the control of your - * own code then you should assume that the person receiving that - * reference may try to use reference counting; you should use - * g_variant_dict_new() instead of this function. - * - * Since: 2.40 - */ - - -/** - * g_variant_dict_insert: - * @dict: a #GVariantDict - * @key: the key to insert a value for - * @format_string: a #GVariant varargs format string - * @...: arguments, as per @format_string - * - * Inserts a value into a #GVariantDict. - * - * This call is a convenience wrapper that is exactly equivalent to - * calling g_variant_new() followed by g_variant_dict_insert_value(). - * - * Since: 2.40 - */ - - -/** - * g_variant_dict_insert_value: - * @dict: a #GVariantDict - * @key: the key to insert a value for - * @value: the value to insert - * - * Inserts (or replaces) a key in a #GVariantDict. - * - * @value is consumed if it is floating. - * - * Since: 2.40 - */ - - -/** - * g_variant_dict_lookup: - * @dict: a #GVariantDict - * @key: the key to look up in the dictionary - * @format_string: a GVariant format string - * @...: the arguments to unpack the value into - * - * Looks up a value in a #GVariantDict. - * - * This function is a wrapper around g_variant_dict_lookup_value() and - * g_variant_get(). In the case that %NULL would have been returned, - * this function returns %FALSE. Otherwise, it unpacks the returned - * value and returns %TRUE. - * - * @format_string determines the C types that are used for unpacking the - * values and also determines if the values are copied or borrowed, see the - * section on [GVariant format strings][gvariant-format-strings-pointers]. - * - * Returns: %TRUE if a value was unpacked - * Since: 2.40 - */ - - -/** - * g_variant_dict_lookup_value: - * @dict: a #GVariantDict - * @key: the key to look up in the dictionary - * @expected_type: (nullable): a #GVariantType, or %NULL - * - * Looks up a value in a #GVariantDict. - * - * If @key is not found in @dictionary, %NULL is returned. - * - * The @expected_type string specifies what type of value is expected. - * If the value associated with @key has a different type then %NULL is - * returned. - * - * If the key is found and the value has the correct type, it is - * returned. If @expected_type was specified then any non-%NULL return - * value will have this type. - * - * Returns: (transfer full): the value of the dictionary key, or %NULL - * Since: 2.40 - */ - - -/** - * g_variant_dict_new: - * @from_asv: (nullable): the #GVariant with which to initialise the - * dictionary - * - * Allocates and initialises a new #GVariantDict. - * - * You should call g_variant_dict_unref() on the return value when it - * is no longer needed. The memory will not be automatically freed by - * any other call. - * - * In some cases it may be easier to place a #GVariantDict directly on - * the stack of the calling function and initialise it with - * g_variant_dict_init(). This is particularly useful when you are - * using #GVariantDict to construct a #GVariant. - * - * Returns: (transfer full): a #GVariantDict - * Since: 2.40 - */ - - -/** - * g_variant_dict_ref: - * @dict: a heap-allocated #GVariantDict - * - * Increases the reference count on @dict. - * - * Don't call this on stack-allocated #GVariantDict instances or bad - * things will happen. - * - * Returns: (transfer full): a new reference to @dict - * Since: 2.40 - */ - - -/** - * g_variant_dict_remove: - * @dict: a #GVariantDict - * @key: the key to remove - * - * Removes a key and its associated value from a #GVariantDict. - * - * Returns: %TRUE if the key was found and removed - * Since: 2.40 - */ - - -/** - * g_variant_dict_unref: - * @dict: (transfer full): a heap-allocated #GVariantDict - * - * Decreases the reference count on @dict. - * - * In the event that there are no more references, releases all memory - * associated with the #GVariantDict. - * - * Don't call this on stack-allocated #GVariantDict instances or bad - * things will happen. - * - * Since: 2.40 - */ - - -/** - * g_variant_dup_bytestring: - * @value: an array-of-bytes #GVariant instance - * @length: (out) (optional) (default NULL): a pointer to a #gsize, to store - * the length (not including the nul terminator) - * - * Similar to g_variant_get_bytestring() except that instead of - * returning a constant string, the string is duplicated. - * - * The return value must be freed using g_free(). - * - * Returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8): - * a newly allocated string - * Since: 2.26 - */ - - -/** - * g_variant_dup_bytestring_array: - * @value: an array of array of bytes #GVariant ('aay') - * @length: (out) (optional): the length of the result, or %NULL - * - * Gets the contents of an array of array of bytes #GVariant. This call - * makes a deep copy; the return result should be released with - * g_strfreev(). - * - * If @length is non-%NULL then the number of elements in the result is - * stored there. In any case, the resulting array will be - * %NULL-terminated. - * - * For an empty array, @length will be set to 0 and a pointer to a - * %NULL pointer will be returned. - * - * Returns: (array length=length) (transfer full): an array of strings - * Since: 2.26 - */ - - -/** - * g_variant_dup_objv: - * @value: an array of object paths #GVariant - * @length: (out) (optional): the length of the result, or %NULL - * - * Gets the contents of an array of object paths #GVariant. This call - * makes a deep copy; the return result should be released with - * g_strfreev(). - * - * If @length is non-%NULL then the number of elements in the result - * is stored there. In any case, the resulting array will be - * %NULL-terminated. - * - * For an empty array, @length will be set to 0 and a pointer to a - * %NULL pointer will be returned. - * - * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings - * Since: 2.30 - */ - - -/** - * g_variant_dup_string: - * @value: a string #GVariant instance - * @length: (out): a pointer to a #gsize, to store the length - * - * Similar to g_variant_get_string() except that instead of returning - * a constant string, the string is duplicated. - * - * The string will always be UTF-8 encoded. - * - * The return value must be freed using g_free(). - * - * Returns: (transfer full): a newly allocated string, UTF-8 encoded - * Since: 2.24 - */ - - -/** - * g_variant_dup_strv: - * @value: an array of strings #GVariant - * @length: (out) (optional): the length of the result, or %NULL - * - * Gets the contents of an array of strings #GVariant. This call - * makes a deep copy; the return result should be released with - * g_strfreev(). - * - * If @length is non-%NULL then the number of elements in the result - * is stored there. In any case, the resulting array will be - * %NULL-terminated. - * - * For an empty array, @length will be set to 0 and a pointer to a - * %NULL pointer will be returned. - * - * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings - * Since: 2.24 - */ - - -/** - * g_variant_equal: - * @one: (type GVariant): a #GVariant instance - * @two: (type GVariant): a #GVariant instance - * - * Checks if @one and @two have the same type and value. - * - * The types of @one and @two are #gconstpointer only to allow use of - * this function with #GHashTable. They must each be a #GVariant. - * - * Returns: %TRUE if @one and @two are equal - * Since: 2.24 - */ - - -/** - * g_variant_get: (skip) - * @value: a #GVariant instance - * @format_string: a #GVariant format string - * @...: arguments, as per @format_string - * - * Deconstructs a #GVariant instance. - * - * Think of this function as an analogue to scanf(). - * - * The arguments that are expected by this function are entirely - * determined by @format_string. @format_string also restricts the - * permissible types of @value. It is an error to give a value with - * an incompatible type. See the section on - * [GVariant format strings][gvariant-format-strings]. - * Please note that the syntax of the format string is very likely to be - * extended in the future. - * - * @format_string determines the C types that are used for unpacking - * the values and also determines if the values are copied or borrowed, - * see the section on - * [GVariant format strings][gvariant-format-strings-pointers]. - * - * Since: 2.24 - */ - - -/** - * g_variant_get_boolean: - * @value: a boolean #GVariant instance - * - * Returns the boolean value of @value. - * - * It is an error to call this function with a @value of any type - * other than %G_VARIANT_TYPE_BOOLEAN. - * - * Returns: %TRUE or %FALSE - * Since: 2.24 - */ - - -/** - * g_variant_get_byte: - * @value: a byte #GVariant instance - * - * Returns the byte value of @value. - * - * It is an error to call this function with a @value of any type - * other than %G_VARIANT_TYPE_BYTE. - * - * Returns: a #guint8 - * Since: 2.24 - */ - - -/** - * g_variant_get_bytestring: - * @value: an array-of-bytes #GVariant instance - * - * Returns the string value of a #GVariant instance with an - * array-of-bytes type. The string has no particular encoding. - * - * If the array does not end with a nul terminator character, the empty - * string is returned. For this reason, you can always trust that a - * non-%NULL nul-terminated string will be returned by this function. - * - * If the array contains a nul terminator character somewhere other than - * the last byte then the returned string is the string, up to the first - * such nul character. - * - * g_variant_get_fixed_array() should be used instead if the array contains - * arbitrary data that could not be nul-terminated or could contain nul bytes. - * - * It is an error to call this function with a @value that is not an - * array of bytes. - * - * The return value remains valid as long as @value exists. - * - * Returns: (transfer none) (array zero-terminated=1) (element-type guint8): - * the constant string - * Since: 2.26 - */ - - -/** - * g_variant_get_bytestring_array: - * @value: an array of array of bytes #GVariant ('aay') - * @length: (out) (optional): the length of the result, or %NULL - * - * Gets the contents of an array of array of bytes #GVariant. This call - * makes a shallow copy; the return result should be released with - * g_free(), but the individual strings must not be modified. - * - * If @length is non-%NULL then the number of elements in the result is - * stored there. In any case, the resulting array will be - * %NULL-terminated. - * - * For an empty array, @length will be set to 0 and a pointer to a - * %NULL pointer will be returned. - * - * Returns: (array length=length) (transfer container): an array of constant strings - * Since: 2.26 - */ - - -/** - * g_variant_get_child: (skip) - * @value: a container #GVariant - * @index_: the index of the child to deconstruct - * @format_string: a #GVariant format string - * @...: arguments, as per @format_string - * - * Reads a child item out of a container #GVariant instance and - * deconstructs it according to @format_string. This call is - * essentially a combination of g_variant_get_child_value() and - * g_variant_get(). - * - * @format_string determines the C types that are used for unpacking - * the values and also determines if the values are copied or borrowed, - * see the section on - * [GVariant format strings][gvariant-format-strings-pointers]. - * - * Since: 2.24 - */ - - -/** - * g_variant_get_child_value: - * @value: a container #GVariant - * @index_: the index of the child to fetch - * - * Reads a child item out of a container #GVariant instance. This - * includes variants, maybes, arrays, tuples and dictionary - * entries. It is an error to call this function on any other type of - * #GVariant. - * - * It is an error if @index_ is greater than the number of child items - * in the container. See g_variant_n_children(). - * - * The returned value is never floating. You should free it with - * g_variant_unref() when you're done with it. - * - * Note that values borrowed from the returned child are not guaranteed to - * still be valid after the child is freed even if you still hold a reference - * to @value, if @value has not been serialized at the time this function is - * called. To avoid this, you can serialize @value by calling - * g_variant_get_data() and optionally ignoring the return value. - * - * There may be implementation specific restrictions on deeply nested values, - * which would result in the unit tuple being returned as the child value, - * instead of further nested children. #GVariant is guaranteed to handle - * nesting up to at least 64 levels. - * - * This function is O(1). - * - * Returns: (transfer full): the child at the specified index - * Since: 2.24 - */ - - -/** - * g_variant_get_data: - * @value: a #GVariant instance - * - * Returns a pointer to the serialized form of a #GVariant instance. - * The returned data may not be in fully-normalised form if read from an - * untrusted source. The returned data must not be freed; it remains - * valid for as long as @value exists. - * - * If @value is a fixed-sized value that was deserialized from a - * corrupted serialized container then %NULL may be returned. In this - * case, the proper thing to do is typically to use the appropriate - * number of nul bytes in place of @value. If @value is not fixed-sized - * then %NULL is never returned. - * - * In the case that @value is already in serialized form, this function - * is O(1). If the value is not already in serialized form, - * serialization occurs implicitly and is approximately O(n) in the size - * of the result. - * - * To deserialize the data returned by this function, in addition to the - * serialized data, you must know the type of the #GVariant, and (if the - * machine might be different) the endianness of the machine that stored - * it. As a result, file formats or network messages that incorporate - * serialized #GVariants must include this information either - * implicitly (for instance "the file always contains a - * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or - * explicitly (by storing the type and/or endianness in addition to the - * serialized data). - * - * Returns: (transfer none): the serialized form of @value, or %NULL - * Since: 2.24 - */ - - -/** - * g_variant_get_data_as_bytes: - * @value: a #GVariant - * - * Returns a pointer to the serialized form of a #GVariant instance. - * The semantics of this function are exactly the same as - * g_variant_get_data(), except that the returned #GBytes holds - * a reference to the variant data. - * - * Returns: (transfer full): A new #GBytes representing the variant data - * Since: 2.36 - */ - - -/** - * g_variant_get_double: - * @value: a double #GVariant instance - * - * Returns the double precision floating point value of @value. - * - * It is an error to call this function with a @value of any type - * other than %G_VARIANT_TYPE_DOUBLE. - * - * Returns: a #gdouble - * Since: 2.24 - */ - - -/** - * g_variant_get_fixed_array: - * @value: a #GVariant array with fixed-sized elements - * @n_elements: (out): a pointer to the location to store the number of items - * @element_size: the size of each element - * - * Provides access to the serialized data for an array of fixed-sized - * items. - * - * @value must be an array with fixed-sized elements. Numeric types are - * fixed-size, as are tuples containing only other fixed-sized types. - * - * @element_size must be the size of a single element in the array, - * as given by the section on - * [serialized data memory][gvariant-serialized-data-memory]. - * - * In particular, arrays of these fixed-sized types can be interpreted - * as an array of the given C type, with @element_size set to the size - * the appropriate type: - * - %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.) - * - %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!) - * - %G_VARIANT_TYPE_BYTE: #guint8 - * - %G_VARIANT_TYPE_HANDLE: #guint32 - * - %G_VARIANT_TYPE_DOUBLE: #gdouble - * - * For example, if calling this function for an array of 32-bit integers, - * you might say `sizeof(gint32)`. This value isn't used except for the purpose - * of a double-check that the form of the serialized data matches the caller's - * expectation. - * - * @n_elements, which must be non-%NULL, is set equal to the number of - * items in the array. - * - * Returns: (array length=n_elements) (transfer none): a pointer to - * the fixed array - * Since: 2.24 - */ - - -/** - * g_variant_get_handle: - * @value: a handle #GVariant instance - * - * Returns the 32-bit signed integer value of @value. - * - * It is an error to call this function with a @value of any type other - * than %G_VARIANT_TYPE_HANDLE. - * - * By convention, handles are indexes into an array of file descriptors - * that are sent alongside a D-Bus message. If you're not interacting - * with D-Bus, you probably don't need them. - * - * Returns: a #gint32 - * Since: 2.24 - */ - - -/** - * g_variant_get_int16: - * @value: an int16 #GVariant instance - * - * Returns the 16-bit signed integer value of @value. - * - * It is an error to call this function with a @value of any type - * other than %G_VARIANT_TYPE_INT16. - * - * Returns: a #gint16 - * Since: 2.24 - */ - - -/** - * g_variant_get_int32: - * @value: an int32 #GVariant instance - * - * Returns the 32-bit signed integer value of @value. - * - * It is an error to call this function with a @value of any type - * other than %G_VARIANT_TYPE_INT32. - * - * Returns: a #gint32 - * Since: 2.24 - */ - - -/** - * g_variant_get_int64: - * @value: an int64 #GVariant instance - * - * Returns the 64-bit signed integer value of @value. - * - * It is an error to call this function with a @value of any type - * other than %G_VARIANT_TYPE_INT64. - * - * Returns: a #gint64 - * Since: 2.24 - */ - - -/** - * g_variant_get_maybe: - * @value: a maybe-typed value - * - * Given a maybe-typed #GVariant instance, extract its value. If the - * value is Nothing, then this function returns %NULL. - * - * Returns: (nullable) (transfer full): the contents of @value, or %NULL - * Since: 2.24 - */ - - -/** - * g_variant_get_normal_form: - * @value: a #GVariant - * - * Gets a #GVariant instance that has the same value as @value and is - * trusted to be in normal form. - * - * If @value is already trusted to be in normal form then a new - * reference to @value is returned. - * - * If @value is not already trusted, then it is scanned to check if it - * is in normal form. If it is found to be in normal form then it is - * marked as trusted and a new reference to it is returned. - * - * If @value is found not to be in normal form then a new trusted - * #GVariant is created with the same value as @value. - * - * It makes sense to call this function if you've received #GVariant - * data from untrusted sources and you want to ensure your serialized - * output is definitely in normal form. - * - * If @value is already in normal form, a new reference will be returned - * (which will be floating if @value is floating). If it is not in normal form, - * the newly created #GVariant will be returned with a single non-floating - * reference. Typically, g_variant_take_ref() should be called on the return - * value from this function to guarantee ownership of a single non-floating - * reference to it. - * - * Returns: (transfer full): a trusted #GVariant - * Since: 2.24 - */ - - -/** - * g_variant_get_objv: - * @value: an array of object paths #GVariant - * @length: (out) (optional): the length of the result, or %NULL - * - * Gets the contents of an array of object paths #GVariant. This call - * makes a shallow copy; the return result should be released with - * g_free(), but the individual strings must not be modified. - * - * If @length is non-%NULL then the number of elements in the result - * is stored there. In any case, the resulting array will be - * %NULL-terminated. - * - * For an empty array, @length will be set to 0 and a pointer to a - * %NULL pointer will be returned. - * - * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings - * Since: 2.30 - */ - - -/** - * g_variant_get_size: - * @value: a #GVariant instance - * - * Determines the number of bytes that would be required to store @value - * with g_variant_store(). - * - * If @value has a fixed-sized type then this function always returned - * that fixed size. - * - * In the case that @value is already in serialized form or the size has - * already been calculated (ie: this function has been called before) - * then this function is O(1). Otherwise, the size is calculated, an - * operation which is approximately O(n) in the number of values - * involved. - * - * Returns: the serialized size of @value - * Since: 2.24 - */ - - -/** - * g_variant_get_string: - * @value: a string #GVariant instance - * @length: (optional) (default 0) (out): a pointer to a #gsize, - * to store the length - * - * Returns the string value of a #GVariant instance with a string - * type. This includes the types %G_VARIANT_TYPE_STRING, - * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. - * - * The string will always be UTF-8 encoded, will never be %NULL, and will never - * contain nul bytes. - * - * If @length is non-%NULL then the length of the string (in bytes) is - * returned there. For trusted values, this information is already - * known. Untrusted values will be validated and, if valid, a strlen() will be - * performed. If invalid, a default value will be returned — for - * %G_VARIANT_TYPE_OBJECT_PATH, this is `"/"`, and for other types it is the - * empty string. - * - * It is an error to call this function with a @value of any type - * other than those three. - * - * The return value remains valid as long as @value exists. - * - * Returns: (transfer none): the constant string, UTF-8 encoded - * Since: 2.24 - */ - - -/** - * g_variant_get_strv: - * @value: an array of strings #GVariant - * @length: (out) (optional): the length of the result, or %NULL - * - * Gets the contents of an array of strings #GVariant. This call - * makes a shallow copy; the return result should be released with - * g_free(), but the individual strings must not be modified. - * - * If @length is non-%NULL then the number of elements in the result - * is stored there. In any case, the resulting array will be - * %NULL-terminated. - * - * For an empty array, @length will be set to 0 and a pointer to a - * %NULL pointer will be returned. - * - * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings - * Since: 2.24 - */ - - -/** - * g_variant_get_type: - * @value: a #GVariant - * - * Determines the type of @value. - * - * The return value is valid for the lifetime of @value and must not - * be freed. - * - * Returns: a #GVariantType - * Since: 2.24 - */ - - -/** - * g_variant_get_type_string: - * @value: a #GVariant - * - * Returns the type string of @value. Unlike the result of calling - * g_variant_type_peek_string(), this string is nul-terminated. This - * string belongs to #GVariant and must not be freed. - * - * Returns: the type string for the type of @value - * Since: 2.24 - */ - - -/** - * g_variant_get_uint16: - * @value: a uint16 #GVariant instance - * - * Returns the 16-bit unsigned integer value of @value. - * - * It is an error to call this function with a @value of any type - * other than %G_VARIANT_TYPE_UINT16. - * - * Returns: a #guint16 - * Since: 2.24 - */ - - -/** - * g_variant_get_uint32: - * @value: a uint32 #GVariant instance - * - * Returns the 32-bit unsigned integer value of @value. - * - * It is an error to call this function with a @value of any type - * other than %G_VARIANT_TYPE_UINT32. - * - * Returns: a #guint32 - * Since: 2.24 - */ - - -/** - * g_variant_get_uint64: - * @value: a uint64 #GVariant instance - * - * Returns the 64-bit unsigned integer value of @value. - * - * It is an error to call this function with a @value of any type - * other than %G_VARIANT_TYPE_UINT64. - * - * Returns: a #guint64 - * Since: 2.24 - */ - - -/** - * g_variant_get_va: (skip) - * @value: a #GVariant - * @format_string: a string that is prefixed with a format string - * @endptr: (nullable) (default NULL): location to store the end pointer, - * or %NULL - * @app: a pointer to a #va_list - * - * This function is intended to be used by libraries based on #GVariant - * that want to provide g_variant_get()-like functionality to their - * users. - * - * The API is more general than g_variant_get() to allow a wider range - * of possible uses. - * - * @format_string must still point to a valid format string, but it only - * need to be nul-terminated if @endptr is %NULL. If @endptr is - * non-%NULL then it is updated to point to the first character past the - * end of the format string. - * - * @app is a pointer to a #va_list. The arguments, according to - * @format_string, are collected from this #va_list and the list is left - * pointing to the argument following the last. - * - * These two generalisations allow mixing of multiple calls to - * g_variant_new_va() and g_variant_get_va() within a single actual - * varargs call by the user. - * - * @format_string determines the C types that are used for unpacking - * the values and also determines if the values are copied or borrowed, - * see the section on - * [GVariant format strings][gvariant-format-strings-pointers]. - * - * Since: 2.24 - */ - - -/** - * g_variant_get_variant: - * @value: a variant #GVariant instance - * - * Unboxes @value. The result is the #GVariant instance that was - * contained in @value. - * - * Returns: (transfer full): the item contained in the variant - * Since: 2.24 - */ - - -/** - * g_variant_hash: - * @value: (type GVariant): a basic #GVariant value as a #gconstpointer - * - * Generates a hash value for a #GVariant instance. - * - * The output of this function is guaranteed to be the same for a given - * value only per-process. It may change between different processor - * architectures or even different versions of GLib. Do not use this - * function as a basis for building protocols or file formats. - * - * The type of @value is #gconstpointer only to allow use of this - * function with #GHashTable. @value must be a #GVariant. - * - * Returns: a hash value corresponding to @value - * Since: 2.24 - */ - - -/** - * g_variant_is_container: - * @value: a #GVariant instance - * - * Checks if @value is a container. - * - * Returns: %TRUE if @value is a container - * Since: 2.24 - */ - - -/** - * g_variant_is_floating: - * @value: a #GVariant - * - * Checks whether @value has a floating reference count. - * - * This function should only ever be used to assert that a given variant - * is or is not floating, or for debug purposes. To acquire a reference - * to a variant that might be floating, always use g_variant_ref_sink() - * or g_variant_take_ref(). - * - * See g_variant_ref_sink() for more information about floating reference - * counts. - * - * Returns: whether @value is floating - * Since: 2.26 - */ - - -/** - * g_variant_is_normal_form: - * @value: a #GVariant instance - * - * Checks if @value is in normal form. - * - * The main reason to do this is to detect if a given chunk of - * serialized data is in normal form: load the data into a #GVariant - * using g_variant_new_from_data() and then use this function to - * check. - * - * If @value is found to be in normal form then it will be marked as - * being trusted. If the value was already marked as being trusted then - * this function will immediately return %TRUE. - * - * There may be implementation specific restrictions on deeply nested values. - * GVariant is guaranteed to handle nesting up to at least 64 levels. - * - * Returns: %TRUE if @value is in normal form - * Since: 2.24 - */ - - -/** - * g_variant_is_object_path: - * @string: a normal C nul-terminated string - * - * Determines if a given string is a valid D-Bus object path. You - * should ensure that a string is a valid D-Bus object path before - * passing it to g_variant_new_object_path(). - * - * A valid object path starts with `/` followed by zero or more - * sequences of characters separated by `/` characters. Each sequence - * must contain only the characters `[A-Z][a-z][0-9]_`. No sequence - * (including the one following the final `/` character) may be empty. - * - * Returns: %TRUE if @string is a D-Bus object path - * Since: 2.24 - */ - - -/** - * g_variant_is_of_type: - * @value: a #GVariant instance - * @type: a #GVariantType - * - * Checks if a value has a type matching the provided type. - * - * Returns: %TRUE if the type of @value matches @type - * Since: 2.24 - */ - - -/** - * g_variant_is_signature: - * @string: a normal C nul-terminated string - * - * Determines if a given string is a valid D-Bus type signature. You - * should ensure that a string is a valid D-Bus type signature before - * passing it to g_variant_new_signature(). - * - * D-Bus type signatures consist of zero or more definite #GVariantType - * strings in sequence. - * - * Returns: %TRUE if @string is a D-Bus type signature - * Since: 2.24 - */ - - -/** - * g_variant_iter_copy: - * @iter: a #GVariantIter - * - * Creates a new heap-allocated #GVariantIter to iterate over the - * container that was being iterated over by @iter. Iteration begins on - * the new iterator from the current position of the old iterator but - * the two copies are independent past that point. - * - * Use g_variant_iter_free() to free the return value when you no longer - * need it. - * - * A reference is taken to the container that @iter is iterating over - * and will be related only when g_variant_iter_free() is called. - * - * Returns: (transfer full): a new heap-allocated #GVariantIter - * Since: 2.24 - */ - - -/** - * g_variant_iter_free: - * @iter: (transfer full): a heap-allocated #GVariantIter - * - * Frees a heap-allocated #GVariantIter. Only call this function on - * iterators that were returned by g_variant_iter_new() or - * g_variant_iter_copy(). - * - * Since: 2.24 - */ - - -/** - * g_variant_iter_init: (skip) - * @iter: a pointer to a #GVariantIter - * @value: a container #GVariant - * - * Initialises (without allocating) a #GVariantIter. @iter may be - * completely uninitialised prior to this call; its old value is - * ignored. - * - * The iterator remains valid for as long as @value exists, and need not - * be freed in any way. - * - * Returns: the number of items in @value - * Since: 2.24 - */ - - -/** - * g_variant_iter_loop: (skip) - * @iter: a #GVariantIter - * @format_string: a GVariant format string - * @...: the arguments to unpack the value into - * - * Gets the next item in the container and unpacks it into the variable - * argument list according to @format_string, returning %TRUE. - * - * If no more items remain then %FALSE is returned. - * - * On the first call to this function, the pointers appearing on the - * variable argument list are assumed to point at uninitialised memory. - * On the second and later calls, it is assumed that the same pointers - * will be given and that they will point to the memory as set by the - * previous call to this function. This allows the previous values to - * be freed, as appropriate. - * - * This function is intended to be used with a while loop as - * demonstrated in the following example. This function can only be - * used when iterating over an array. It is only valid to call this - * function with a string constant for the format string and the same - * string constant must be used each time. Mixing calls to this - * function and g_variant_iter_next() or g_variant_iter_next_value() on - * the same iterator causes undefined behavior. - * - * If you break out of a such a while loop using g_variant_iter_loop() then - * you must free or unreference all the unpacked values as you would with - * g_variant_get(). Failure to do so will cause a memory leak. - * - * Here is an example for memory management with g_variant_iter_loop(): - * |[<!-- language="C" --> - * // Iterates a dictionary of type 'a{sv}' - * void - * iterate_dictionary (GVariant *dictionary) - * { - * GVariantIter iter; - * GVariant *value; - * gchar *key; - * - * g_variant_iter_init (&iter, dictionary); - * while (g_variant_iter_loop (&iter, "{sv}", &key, &value)) - * { - * g_print ("Item '%s' has type '%s'\n", key, - * g_variant_get_type_string (value)); - * - * // no need to free 'key' and 'value' here - * // unless breaking out of this loop - * } - * } - * ]| - * - * For most cases you should use g_variant_iter_next(). - * - * This function is really only useful when unpacking into #GVariant or - * #GVariantIter in order to allow you to skip the call to - * g_variant_unref() or g_variant_iter_free(). - * - * For example, if you are only looping over simple integer and string - * types, g_variant_iter_next() is definitely preferred. For string - * types, use the '&' prefix to avoid allocating any memory at all (and - * thereby avoiding the need to free anything as well). - * - * @format_string determines the C types that are used for unpacking - * the values and also determines if the values are copied or borrowed. - * - * See the section on - * [GVariant format strings][gvariant-format-strings-pointers]. - * - * Returns: %TRUE if a value was unpacked, or %FALSE if there was no - * value - * Since: 2.24 - */ - - -/** - * g_variant_iter_n_children: - * @iter: a #GVariantIter - * - * Queries the number of child items in the container that we are - * iterating over. This is the total number of items -- not the number - * of items remaining. - * - * This function might be useful for preallocation of arrays. - * - * Returns: the number of children in the container - * Since: 2.24 - */ - - -/** - * g_variant_iter_new: - * @value: a container #GVariant - * - * Creates a heap-allocated #GVariantIter for iterating over the items - * in @value. - * - * Use g_variant_iter_free() to free the return value when you no longer - * need it. - * - * A reference is taken to @value and will be released only when - * g_variant_iter_free() is called. - * - * Returns: (transfer full): a new heap-allocated #GVariantIter - * Since: 2.24 - */ - - -/** - * g_variant_iter_next: (skip) - * @iter: a #GVariantIter - * @format_string: a GVariant format string - * @...: the arguments to unpack the value into - * - * Gets the next item in the container and unpacks it into the variable - * argument list according to @format_string, returning %TRUE. - * - * If no more items remain then %FALSE is returned. - * - * All of the pointers given on the variable arguments list of this - * function are assumed to point at uninitialised memory. It is the - * responsibility of the caller to free all of the values returned by - * the unpacking process. - * - * Here is an example for memory management with g_variant_iter_next(): - * |[<!-- language="C" --> - * // Iterates a dictionary of type 'a{sv}' - * void - * iterate_dictionary (GVariant *dictionary) - * { - * GVariantIter iter; - * GVariant *value; - * gchar *key; - * - * g_variant_iter_init (&iter, dictionary); - * while (g_variant_iter_next (&iter, "{sv}", &key, &value)) - * { - * g_print ("Item '%s' has type '%s'\n", key, - * g_variant_get_type_string (value)); - * - * // must free data for ourselves - * g_variant_unref (value); - * g_free (key); - * } - * } - * ]| - * - * For a solution that is likely to be more convenient to C programmers - * when dealing with loops, see g_variant_iter_loop(). - * - * @format_string determines the C types that are used for unpacking - * the values and also determines if the values are copied or borrowed. - * - * See the section on - * [GVariant format strings][gvariant-format-strings-pointers]. - * - * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value - * Since: 2.24 - */ - - -/** - * g_variant_iter_next_value: - * @iter: a #GVariantIter - * - * Gets the next item in the container. If no more items remain then - * %NULL is returned. - * - * Use g_variant_unref() to drop your reference on the return value when - * you no longer need it. - * - * Here is an example for iterating with g_variant_iter_next_value(): - * |[<!-- language="C" --> - * // recursively iterate a container - * void - * iterate_container_recursive (GVariant *container) - * { - * GVariantIter iter; - * GVariant *child; - * - * g_variant_iter_init (&iter, container); - * while ((child = g_variant_iter_next_value (&iter))) - * { - * g_print ("type '%s'\n", g_variant_get_type_string (child)); - * - * if (g_variant_is_container (child)) - * iterate_container_recursive (child); - * - * g_variant_unref (child); - * } - * } - * ]| - * - * Returns: (nullable) (transfer full): a #GVariant, or %NULL - * Since: 2.24 - */ - - -/** - * g_variant_lookup: (skip) - * @dictionary: a dictionary #GVariant - * @key: the key to look up in the dictionary - * @format_string: a GVariant format string - * @...: the arguments to unpack the value into - * - * Looks up a value in a dictionary #GVariant. - * - * This function is a wrapper around g_variant_lookup_value() and - * g_variant_get(). In the case that %NULL would have been returned, - * this function returns %FALSE. Otherwise, it unpacks the returned - * value and returns %TRUE. - * - * @format_string determines the C types that are used for unpacking - * the values and also determines if the values are copied or borrowed, - * see the section on - * [GVariant format strings][gvariant-format-strings-pointers]. - * - * This function is currently implemented with a linear scan. If you - * plan to do many lookups then #GVariantDict may be more efficient. - * - * Returns: %TRUE if a value was unpacked - * Since: 2.28 - */ - - -/** - * g_variant_lookup_value: - * @dictionary: a dictionary #GVariant - * @key: the key to look up in the dictionary - * @expected_type: (nullable): a #GVariantType, or %NULL - * - * Looks up a value in a dictionary #GVariant. - * - * This function works with dictionaries of the type a{s*} (and equally - * well with type a{o*}, but we only further discuss the string case - * for sake of clarity). - * - * In the event that @dictionary has the type a{sv}, the @expected_type - * string specifies what type of value is expected to be inside of the - * variant. If the value inside the variant has a different type then - * %NULL is returned. In the event that @dictionary has a value type other - * than v then @expected_type must directly match the value type and it is - * used to unpack the value directly or an error occurs. - * - * In either case, if @key is not found in @dictionary, %NULL is returned. - * - * If the key is found and the value has the correct type, it is - * returned. If @expected_type was specified then any non-%NULL return - * value will have this type. - * - * This function is currently implemented with a linear scan. If you - * plan to do many lookups then #GVariantDict may be more efficient. - * - * Returns: (transfer full): the value of the dictionary key, or %NULL - * Since: 2.28 - */ - - -/** - * g_variant_n_children: - * @value: a container #GVariant - * - * Determines the number of children in a container #GVariant instance. - * This includes variants, maybes, arrays, tuples and dictionary - * entries. It is an error to call this function on any other type of - * #GVariant. - * - * For variants, the return value is always 1. For values with maybe - * types, it is always zero or one. For arrays, it is the length of the - * array. For tuples it is the number of tuple items (which depends - * only on the type). For dictionary entries, it is always 2 - * - * This function is O(1). - * - * Returns: the number of children in the container - * Since: 2.24 - */ - - -/** - * g_variant_new: (skip) - * @format_string: a #GVariant format string - * @...: arguments, as per @format_string - * - * Creates a new #GVariant instance. - * - * Think of this function as an analogue to g_strdup_printf(). - * - * The type of the created instance and the arguments that are expected - * by this function are determined by @format_string. See the section on - * [GVariant format strings][gvariant-format-strings]. Please note that - * the syntax of the format string is very likely to be extended in the - * future. - * - * The first character of the format string must not be '*' '?' '@' or - * 'r'; in essence, a new #GVariant must always be constructed by this - * function (and not merely passed through it unmodified). - * - * Note that the arguments must be of the correct width for their types - * specified in @format_string. This can be achieved by casting them. See - * the [GVariant varargs documentation][gvariant-varargs]. - * - * |[<!-- language="C" --> - * MyFlags some_flags = FLAG_ONE | FLAG_TWO; - * const gchar *some_strings[] = { "a", "b", "c", NULL }; - * GVariant *new_variant; - * - * new_variant = g_variant_new ("(t^as)", - * // This cast is required. - * (guint64) some_flags, - * some_strings); - * ]| - * - * Returns: a new floating #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_array: - * @child_type: (nullable): the element type of the new array - * @children: (nullable) (array length=n_children): an array of - * #GVariant pointers, the children - * @n_children: the length of @children - * - * Creates a new #GVariant array from @children. - * - * @child_type must be non-%NULL if @n_children is zero. Otherwise, the - * child type is determined by inspecting the first element of the - * @children array. If @child_type is non-%NULL then it must be a - * definite type. - * - * The items of the array are taken from the @children array. No entry - * in the @children array may be %NULL. - * - * All items in the array must have the same type, which must be the - * same as @child_type, if given. - * - * If the @children are floating references (see g_variant_ref_sink()), the - * new instance takes ownership of them as if via g_variant_ref_sink(). - * - * Returns: (transfer none): a floating reference to a new #GVariant array - * Since: 2.24 - */ - - -/** - * g_variant_new_boolean: - * @value: a #gboolean value - * - * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE. - * - * Returns: (transfer none): a floating reference to a new boolean #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_byte: - * @value: a #guint8 value - * - * Creates a new byte #GVariant instance. - * - * Returns: (transfer none): a floating reference to a new byte #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_bytestring: - * @string: (array zero-terminated=1) (element-type guint8): a normal - * nul-terminated string in no particular encoding - * - * Creates an array-of-bytes #GVariant with the contents of @string. - * This function is just like g_variant_new_string() except that the - * string need not be valid UTF-8. - * - * The nul terminator character at the end of the string is stored in - * the array. - * - * Returns: (transfer none): a floating reference to a new bytestring #GVariant instance - * Since: 2.26 - */ - - -/** - * g_variant_new_bytestring_array: - * @strv: (array length=length): an array of strings - * @length: the length of @strv, or -1 - * - * Constructs an array of bytestring #GVariant from the given array of - * strings. - * - * If @length is -1 then @strv is %NULL-terminated. - * - * Returns: (transfer none): a new floating #GVariant instance - * Since: 2.26 - */ - - -/** - * g_variant_new_dict_entry: (constructor) - * @key: a basic #GVariant, the key - * @value: a #GVariant, the value - * - * Creates a new dictionary entry #GVariant. @key and @value must be - * non-%NULL. @key must be a value of a basic type (ie: not a container). - * - * If the @key or @value are floating references (see g_variant_ref_sink()), - * the new instance takes ownership of them as if via g_variant_ref_sink(). - * - * Returns: (transfer none): a floating reference to a new dictionary entry #GVariant - * Since: 2.24 - */ - - -/** - * g_variant_new_double: - * @value: a #gdouble floating point value - * - * Creates a new double #GVariant instance. - * - * Returns: (transfer none): a floating reference to a new double #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_fixed_array: - * @element_type: the #GVariantType of each element - * @elements: a pointer to the fixed array of contiguous elements - * @n_elements: the number of elements - * @element_size: the size of each element - * - * Constructs a new array #GVariant instance, where the elements are - * of @element_type type. - * - * @elements must be an array with fixed-sized elements. Numeric types are - * fixed-size as are tuples containing only other fixed-sized types. - * - * @element_size must be the size of a single element in the array. - * For example, if calling this function for an array of 32-bit integers, - * you might say sizeof(gint32). This value isn't used except for the purpose - * of a double-check that the form of the serialized data matches the caller's - * expectation. - * - * @n_elements must be the length of the @elements array. - * - * Returns: (transfer none): a floating reference to a new array #GVariant instance - * Since: 2.32 - */ - - -/** - * g_variant_new_from_bytes: - * @type: a #GVariantType - * @bytes: a #GBytes - * @trusted: if the contents of @bytes are trusted - * - * Constructs a new serialized-mode #GVariant instance. This is the - * inner interface for creation of new serialized values that gets - * called from various functions in gvariant.c. - * - * A reference is taken on @bytes. - * - * The data in @bytes must be aligned appropriately for the @type being loaded. - * Otherwise this function will internally create a copy of the memory (since - * GLib 2.60) or (in older versions) fail and exit the process. - * - * Returns: (transfer none): a new #GVariant with a floating reference - * Since: 2.36 - */ - - -/** - * g_variant_new_from_data: - * @type: a definite #GVariantType - * @data: (array length=size) (element-type guint8): the serialized data - * @size: the size of @data - * @trusted: %TRUE if @data is definitely in normal form - * @notify: (scope async): function to call when @data is no longer needed - * @user_data: data for @notify - * - * Creates a new #GVariant instance from serialized data. - * - * @type is the type of #GVariant instance that will be constructed. - * The interpretation of @data depends on knowing the type. - * - * @data is not modified by this function and must remain valid with an - * unchanging value until such a time as @notify is called with - * @user_data. If the contents of @data change before that time then - * the result is undefined. - * - * If @data is trusted to be serialized data in normal form then - * @trusted should be %TRUE. This applies to serialized data created - * within this process or read from a trusted location on the disk (such - * as a file installed in /usr/lib alongside your application). You - * should set trusted to %FALSE if @data is read from the network, a - * file in the user's home directory, etc. - * - * If @data was not stored in this machine's native endianness, any multi-byte - * numeric values in the returned variant will also be in non-native - * endianness. g_variant_byteswap() can be used to recover the original values. - * - * @notify will be called with @user_data when @data is no longer - * needed. The exact time of this call is unspecified and might even be - * before this function returns. - * - * Note: @data must be backed by memory that is aligned appropriately for the - * @type being loaded. Otherwise this function will internally create a copy of - * the memory (since GLib 2.60) or (in older versions) fail and exit the - * process. - * - * Returns: (transfer none): a new floating #GVariant of type @type - * Since: 2.24 - */ - - -/** - * g_variant_new_handle: - * @value: a #gint32 value - * - * Creates a new handle #GVariant instance. - * - * By convention, handles are indexes into an array of file descriptors - * that are sent alongside a D-Bus message. If you're not interacting - * with D-Bus, you probably don't need them. - * - * Returns: (transfer none): a floating reference to a new handle #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_int16: - * @value: a #gint16 value - * - * Creates a new int16 #GVariant instance. - * - * Returns: (transfer none): a floating reference to a new int16 #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_int32: - * @value: a #gint32 value - * - * Creates a new int32 #GVariant instance. - * - * Returns: (transfer none): a floating reference to a new int32 #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_int64: - * @value: a #gint64 value - * - * Creates a new int64 #GVariant instance. - * - * Returns: (transfer none): a floating reference to a new int64 #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_maybe: - * @child_type: (nullable): the #GVariantType of the child, or %NULL - * @child: (nullable): the child value, or %NULL - * - * Depending on if @child is %NULL, either wraps @child inside of a - * maybe container or creates a Nothing instance for the given @type. - * - * At least one of @child_type and @child must be non-%NULL. - * If @child_type is non-%NULL then it must be a definite type. - * If they are both non-%NULL then @child_type must be the type - * of @child. - * - * If @child is a floating reference (see g_variant_ref_sink()), the new - * instance takes ownership of @child. - * - * Returns: (transfer none): a floating reference to a new #GVariant maybe instance - * Since: 2.24 - */ - - -/** - * g_variant_new_object_path: - * @object_path: a normal C nul-terminated string - * - * Creates a D-Bus object path #GVariant with the contents of @string. - * @string must be a valid D-Bus object path. Use - * g_variant_is_object_path() if you're not sure. - * - * Returns: (transfer none): a floating reference to a new object path #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_objv: - * @strv: (array length=length) (element-type utf8): an array of strings - * @length: the length of @strv, or -1 - * - * Constructs an array of object paths #GVariant from the given array of - * strings. - * - * Each string must be a valid #GVariant object path; see - * g_variant_is_object_path(). - * - * If @length is -1 then @strv is %NULL-terminated. - * - * Returns: (transfer none): a new floating #GVariant instance - * Since: 2.30 - */ - - -/** - * g_variant_new_parsed: - * @format: a text format #GVariant - * @...: arguments as per @format - * - * Parses @format and returns the result. - * - * @format must be a text format #GVariant with one extension: at any - * point that a value may appear in the text, a '%' character followed - * by a GVariant format string (as per g_variant_new()) may appear. In - * that case, the same arguments are collected from the argument list as - * g_variant_new() would have collected. - * - * Note that the arguments must be of the correct width for their types - * specified in @format. This can be achieved by casting them. See - * the [GVariant varargs documentation][gvariant-varargs]. - * - * Consider this simple example: - * |[<!-- language="C" --> - * g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three"); - * ]| - * - * In the example, the variable argument parameters are collected and - * filled in as if they were part of the original string to produce the - * result of - * |[<!-- language="C" --> - * [('one', 1), ('two', 2), ('three', 3)] - * ]| - * - * This function is intended only to be used with @format as a string - * literal. Any parse error is fatal to the calling process. If you - * want to parse data from untrusted sources, use g_variant_parse(). - * - * You may not use this function to return, unmodified, a single - * #GVariant pointer from the argument list. ie: @format may not solely - * be anything along the lines of "%*", "%?", "\%r", or anything starting - * with "%@". - * - * Returns: a new floating #GVariant instance - */ - - -/** - * g_variant_new_parsed_va: - * @format: a text format #GVariant - * @app: a pointer to a #va_list - * - * Parses @format and returns the result. - * - * This is the version of g_variant_new_parsed() intended to be used - * from libraries. - * - * The return value will be floating if it was a newly created GVariant - * instance. In the case that @format simply specified the collection - * of a #GVariant pointer (eg: @format was "%*") then the collected - * #GVariant pointer will be returned unmodified, without adding any - * additional references. - * - * Note that the arguments in @app must be of the correct width for their types - * specified in @format when collected into the #va_list. See - * the [GVariant varargs documentation][gvariant-varargs]. - * - * In order to behave correctly in all cases it is necessary for the - * calling function to g_variant_ref_sink() the return result before - * returning control to the user that originally provided the pointer. - * At this point, the caller will have their own full reference to the - * result. This can also be done by adding the result to a container, - * or by passing it to another g_variant_new() call. - * - * Returns: a new, usually floating, #GVariant - */ - - -/** - * g_variant_new_printf: (skip) - * @format_string: a printf-style format string - * @...: arguments for @format_string - * - * Creates a string-type GVariant using printf formatting. - * - * This is similar to calling g_strdup_printf() and then - * g_variant_new_string() but it saves a temporary variable and an - * unnecessary copy. - * - * Returns: (transfer none): a floating reference to a new string - * #GVariant instance - * Since: 2.38 - */ - - -/** - * g_variant_new_signature: - * @signature: a normal C nul-terminated string - * - * Creates a D-Bus type signature #GVariant with the contents of - * @string. @string must be a valid D-Bus type signature. Use - * g_variant_is_signature() if you're not sure. - * - * Returns: (transfer none): a floating reference to a new signature #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_string: - * @string: a normal UTF-8 nul-terminated string - * - * Creates a string #GVariant with the contents of @string. - * - * @string must be valid UTF-8, and must not be %NULL. To encode - * potentially-%NULL strings, use g_variant_new() with `ms` as the - * [format string][gvariant-format-strings-maybe-types]. - * - * Returns: (transfer none): a floating reference to a new string #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_strv: - * @strv: (array length=length) (element-type utf8): an array of strings - * @length: the length of @strv, or -1 - * - * Constructs an array of strings #GVariant from the given array of - * strings. - * - * If @length is -1 then @strv is %NULL-terminated. - * - * Returns: (transfer none): a new floating #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_take_string: (skip) - * @string: a normal UTF-8 nul-terminated string - * - * Creates a string #GVariant with the contents of @string. - * - * @string must be valid UTF-8, and must not be %NULL. To encode - * potentially-%NULL strings, use this with g_variant_new_maybe(). - * - * This function consumes @string. g_free() will be called on @string - * when it is no longer required. - * - * You must not modify or access @string in any other way after passing - * it to this function. It is even possible that @string is immediately - * freed. - * - * Returns: (transfer none): a floating reference to a new string - * #GVariant instance - * Since: 2.38 - */ - - -/** - * g_variant_new_tuple: - * @children: (array length=n_children): the items to make the tuple out of - * @n_children: the length of @children - * - * Creates a new tuple #GVariant out of the items in @children. The - * type is determined from the types of @children. No entry in the - * @children array may be %NULL. - * - * If @n_children is 0 then the unit tuple is constructed. - * - * If the @children are floating references (see g_variant_ref_sink()), the - * new instance takes ownership of them as if via g_variant_ref_sink(). - * - * Returns: (transfer none): a floating reference to a new #GVariant tuple - * Since: 2.24 - */ - - -/** - * g_variant_new_uint16: - * @value: a #guint16 value - * - * Creates a new uint16 #GVariant instance. - * - * Returns: (transfer none): a floating reference to a new uint16 #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_uint32: - * @value: a #guint32 value - * - * Creates a new uint32 #GVariant instance. - * - * Returns: (transfer none): a floating reference to a new uint32 #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_uint64: - * @value: a #guint64 value - * - * Creates a new uint64 #GVariant instance. - * - * Returns: (transfer none): a floating reference to a new uint64 #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_new_va: (skip) - * @format_string: a string that is prefixed with a format string - * @endptr: (nullable) (default NULL): location to store the end pointer, - * or %NULL - * @app: a pointer to a #va_list - * - * This function is intended to be used by libraries based on - * #GVariant that want to provide g_variant_new()-like functionality - * to their users. - * - * The API is more general than g_variant_new() to allow a wider range - * of possible uses. - * - * @format_string must still point to a valid format string, but it only - * needs to be nul-terminated if @endptr is %NULL. If @endptr is - * non-%NULL then it is updated to point to the first character past the - * end of the format string. - * - * @app is a pointer to a #va_list. The arguments, according to - * @format_string, are collected from this #va_list and the list is left - * pointing to the argument following the last. - * - * Note that the arguments in @app must be of the correct width for their - * types specified in @format_string when collected into the #va_list. - * See the [GVariant varargs documentation][gvariant-varargs]. - * - * These two generalisations allow mixing of multiple calls to - * g_variant_new_va() and g_variant_get_va() within a single actual - * varargs call by the user. - * - * The return value will be floating if it was a newly created GVariant - * instance (for example, if the format string was "(ii)"). In the case - * that the format_string was '*', '?', 'r', or a format starting with - * '@' then the collected #GVariant pointer will be returned unmodified, - * without adding any additional references. - * - * In order to behave correctly in all cases it is necessary for the - * calling function to g_variant_ref_sink() the return result before - * returning control to the user that originally provided the pointer. - * At this point, the caller will have their own full reference to the - * result. This can also be done by adding the result to a container, - * or by passing it to another g_variant_new() call. - * - * Returns: a new, usually floating, #GVariant - * Since: 2.24 - */ - - -/** - * g_variant_new_variant: (constructor) - * @value: a #GVariant instance - * - * Boxes @value. The result is a #GVariant instance representing a - * variant containing the original value. - * - * If @child is a floating reference (see g_variant_ref_sink()), the new - * instance takes ownership of @child. - * - * Returns: (transfer none): a floating reference to a new variant #GVariant instance - * Since: 2.24 - */ - - -/** - * g_variant_parse: - * @type: (nullable): a #GVariantType, or %NULL - * @text: a string containing a GVariant in text form - * @limit: (nullable): a pointer to the end of @text, or %NULL - * @endptr: (nullable): a location to store the end pointer, or %NULL - * @error: (nullable): a pointer to a %NULL #GError pointer, or %NULL - * - * Parses a #GVariant from a text representation. - * - * A single #GVariant is parsed from the content of @text. - * - * The format is described [here][gvariant-text]. - * - * The memory at @limit will never be accessed and the parser behaves as - * if the character at @limit is the nul terminator. This has the - * effect of bounding @text. - * - * If @endptr is non-%NULL then @text is permitted to contain data - * following the value that this function parses and @endptr will be - * updated to point to the first character past the end of the text - * parsed by this function. If @endptr is %NULL and there is extra data - * then an error is returned. - * - * If @type is non-%NULL then the value will be parsed to have that - * type. This may result in additional parse errors (in the case that - * the parsed value doesn't fit the type) but may also result in fewer - * errors (in the case that the type would have been ambiguous, such as - * with empty arrays). - * - * In the event that the parsing is successful, the resulting #GVariant - * is returned. It is never floating, and must be freed with - * g_variant_unref(). - * - * In case of any error, %NULL will be returned. If @error is non-%NULL - * then it will be set to reflect the error that occurred. - * - * Officially, the language understood by the parser is "any string - * produced by g_variant_print()". - * - * There may be implementation specific restrictions on deeply nested values, - * which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is - * guaranteed to handle nesting up to at least 64 levels. - * - * Returns: a non-floating reference to a #GVariant, or %NULL - */ - - -/** - * g_variant_parse_error_print_context: - * @error: a #GError from the #GVariantParseError domain - * @source_str: the string that was given to the parser - * - * Pretty-prints a message showing the context of a #GVariant parse - * error within the string for which parsing was attempted. - * - * The resulting string is suitable for output to the console or other - * monospace media where newlines are treated in the usual way. - * - * The message will typically look something like one of the following: - * - * |[ - * unterminated string constant: - * (1, 2, 3, 'abc - * ^^^^ - * ]| - * - * or - * - * |[ - * unable to find a common type: - * [1, 2, 3, 'str'] - * ^ ^^^^^ - * ]| - * - * The format of the message may change in a future version. - * - * @error must have come from a failed attempt to g_variant_parse() and - * @source_str must be exactly the same string that caused the error. - * If @source_str was not nul-terminated when you passed it to - * g_variant_parse() then you must add nul termination before using this - * function. - * - * Returns: (transfer full): the printed message - * Since: 2.40 - */ - - -/** - * g_variant_parser_get_error_quark: - * - * Same as g_variant_error_quark(). - * - * Deprecated: Use g_variant_parse_error_quark() instead. - */ - - -/** - * g_variant_print: - * @value: a #GVariant - * @type_annotate: %TRUE if type information should be included in - * the output - * - * Pretty-prints @value in the format understood by g_variant_parse(). - * - * The format is described [here][gvariant-text]. - * - * If @type_annotate is %TRUE, then type information is included in - * the output. - * - * Returns: (transfer full): a newly-allocated string holding the result. - * Since: 2.24 - */ - - -/** - * g_variant_print_string: (skip) - * @value: a #GVariant - * @string: (nullable) (default NULL): a #GString, or %NULL - * @type_annotate: %TRUE if type information should be included in - * the output - * - * Behaves as g_variant_print(), but operates on a #GString. - * - * If @string is non-%NULL then it is appended to and returned. Else, - * a new empty #GString is allocated and it is returned. - * - * Returns: a #GString containing the string - * Since: 2.24 - */ - - -/** - * g_variant_ref: - * @value: a #GVariant - * - * Increases the reference count of @value. - * - * Returns: the same @value - * Since: 2.24 - */ - - -/** - * g_variant_ref_sink: - * @value: a #GVariant - * - * #GVariant uses a floating reference count system. All functions with - * names starting with `g_variant_new_` return floating - * references. - * - * Calling g_variant_ref_sink() on a #GVariant with a floating reference - * will convert the floating reference into a full reference. Calling - * g_variant_ref_sink() on a non-floating #GVariant results in an - * additional normal reference being added. - * - * In other words, if the @value is floating, then this call "assumes - * ownership" of the floating reference, converting it to a normal - * reference. If the @value is not floating, then this call adds a - * new normal reference increasing the reference count by one. - * - * All calls that result in a #GVariant instance being inserted into a - * container will call g_variant_ref_sink() on the instance. This means - * that if the value was just created (and has only its floating - * reference) then the container will assume sole ownership of the value - * at that point and the caller will not need to unreference it. This - * makes certain common styles of programming much easier while still - * maintaining normal refcounting semantics in situations where values - * are not floating. - * - * Returns: the same @value - * Since: 2.24 - */ - - -/** - * g_variant_store: - * @value: the #GVariant to store - * @data: (not nullable): the location to store the serialized data at - * - * Stores the serialized form of @value at @data. @data should be - * large enough. See g_variant_get_size(). - * - * The stored data is in machine native byte order but may not be in - * fully-normalised form if read from an untrusted source. See - * g_variant_get_normal_form() for a solution. - * - * As with g_variant_get_data(), to be able to deserialize the - * serialized variant successfully, its type and (if the destination - * machine might be different) its endianness must also be available. - * - * This function is approximately O(n) in the size of @data. - * - * Since: 2.24 - */ - - -/** - * g_variant_take_ref: - * @value: a #GVariant - * - * If @value is floating, sink it. Otherwise, do nothing. - * - * Typically you want to use g_variant_ref_sink() in order to - * automatically do the correct thing with respect to floating or - * non-floating references, but there is one specific scenario where - * this function is helpful. - * - * The situation where this function is helpful is when creating an API - * that allows the user to provide a callback function that returns a - * #GVariant. We certainly want to allow the user the flexibility to - * return a non-floating reference from this callback (for the case - * where the value that is being returned already exists). - * - * At the same time, the style of the #GVariant API makes it likely that - * for newly-created #GVariant instances, the user can be saved some - * typing if they are allowed to return a #GVariant with a floating - * reference. - * - * Using this function on the return value of the user's callback allows - * the user to do whichever is more convenient for them. The caller - * will always receives exactly one full reference to the value: either - * the one that was returned in the first place, or a floating reference - * that has been converted to a full reference. - * - * This function has an odd interaction when combined with - * g_variant_ref_sink() running at the same time in another thread on - * the same #GVariant instance. If g_variant_ref_sink() runs first then - * the result will be that the floating reference is converted to a hard - * reference. If g_variant_take_ref() runs first then the result will - * be that the floating reference is converted to a hard reference and - * an additional reference on top of that one is added. It is best to - * avoid this situation. - * - * Returns: the same @value - */ - - -/** - * g_variant_type_copy: - * @type: a #GVariantType - * - * Makes a copy of a #GVariantType. It is appropriate to call - * g_variant_type_free() on the return value. @type may not be %NULL. - * - * Returns: (transfer full): a new #GVariantType - * - * Since 2.24 - */ - - -/** - * g_variant_type_dup_string: - * @type: a #GVariantType - * - * Returns a newly-allocated copy of the type string corresponding to - * @type. The returned string is nul-terminated. It is appropriate to - * call g_free() on the return value. - * - * Returns: (transfer full): the corresponding type string - * - * Since 2.24 - */ - - -/** - * g_variant_type_element: - * @type: an array or maybe #GVariantType - * - * Determines the element type of an array or maybe type. - * - * This function may only be used with array or maybe types. - * - * Returns: (transfer none): the element type of @type - * - * Since 2.24 - */ - - -/** - * g_variant_type_equal: - * @type1: (type GVariantType): a #GVariantType - * @type2: (type GVariantType): a #GVariantType - * - * Compares @type1 and @type2 for equality. - * - * Only returns %TRUE if the types are exactly equal. Even if one type - * is an indefinite type and the other is a subtype of it, %FALSE will - * be returned if they are not exactly equal. If you want to check for - * subtypes, use g_variant_type_is_subtype_of(). - * - * The argument types of @type1 and @type2 are only #gconstpointer to - * allow use with #GHashTable without function pointer casting. For - * both arguments, a valid #GVariantType must be provided. - * - * Returns: %TRUE if @type1 and @type2 are exactly equal - * - * Since 2.24 - */ - - -/** - * g_variant_type_first: - * @type: a tuple or dictionary entry #GVariantType - * - * Determines the first item type of a tuple or dictionary entry - * type. - * - * This function may only be used with tuple or dictionary entry types, - * but must not be used with the generic tuple type - * %G_VARIANT_TYPE_TUPLE. - * - * In the case of a dictionary entry type, this returns the type of - * the key. - * - * %NULL is returned in case of @type being %G_VARIANT_TYPE_UNIT. - * - * This call, together with g_variant_type_next() provides an iterator - * interface over tuple and dictionary entry types. - * - * Returns: (transfer none): the first item type of @type, or %NULL - * - * Since 2.24 - */ - - -/** - * g_variant_type_free: - * @type: (nullable): a #GVariantType, or %NULL - * - * Frees a #GVariantType that was allocated with - * g_variant_type_copy(), g_variant_type_new() or one of the container - * type constructor functions. - * - * In the case that @type is %NULL, this function does nothing. - * - * Since 2.24 - */ - - -/** - * g_variant_type_get_string_length: - * @type: a #GVariantType - * - * Returns the length of the type string corresponding to the given - * @type. This function must be used to determine the valid extent of - * the memory region returned by g_variant_type_peek_string(). - * - * Returns: the length of the corresponding type string - * - * Since 2.24 - */ - - -/** - * g_variant_type_hash: - * @type: (type GVariantType): a #GVariantType - * - * Hashes @type. - * - * The argument type of @type is only #gconstpointer to allow use with - * #GHashTable without function pointer casting. A valid - * #GVariantType must be provided. - * - * Returns: the hash value - * - * Since 2.24 - */ - - -/** - * g_variant_type_is_array: - * @type: a #GVariantType - * - * Determines if the given @type is an array type. This is true if the - * type string for @type starts with an 'a'. - * - * This function returns %TRUE for any indefinite type for which every - * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for - * example. - * - * Returns: %TRUE if @type is an array type - * - * Since 2.24 - */ - - -/** - * g_variant_type_is_basic: - * @type: a #GVariantType - * - * Determines if the given @type is a basic type. - * - * Basic types are booleans, bytes, integers, doubles, strings, object - * paths and signatures. - * - * Only a basic type may be used as the key of a dictionary entry. - * - * This function returns %FALSE for all indefinite types except - * %G_VARIANT_TYPE_BASIC. - * - * Returns: %TRUE if @type is a basic type - * - * Since 2.24 - */ - - -/** - * g_variant_type_is_container: - * @type: a #GVariantType - * - * Determines if the given @type is a container type. - * - * Container types are any array, maybe, tuple, or dictionary - * entry types plus the variant type. - * - * This function returns %TRUE for any indefinite type for which every - * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for - * example. - * - * Returns: %TRUE if @type is a container type - * - * Since 2.24 - */ - - -/** - * g_variant_type_is_definite: - * @type: a #GVariantType - * - * Determines if the given @type is definite (ie: not indefinite). - * - * A type is definite if its type string does not contain any indefinite - * type characters ('*', '?', or 'r'). - * - * A #GVariant instance may not have an indefinite type, so calling - * this function on the result of g_variant_get_type() will always - * result in %TRUE being returned. Calling this function on an - * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in - * %FALSE being returned. - * - * Returns: %TRUE if @type is definite - * - * Since 2.24 - */ - - -/** - * g_variant_type_is_dict_entry: - * @type: a #GVariantType - * - * Determines if the given @type is a dictionary entry type. This is - * true if the type string for @type starts with a '{'. - * - * This function returns %TRUE for any indefinite type for which every - * definite subtype is a dictionary entry type -- - * %G_VARIANT_TYPE_DICT_ENTRY, for example. - * - * Returns: %TRUE if @type is a dictionary entry type - * - * Since 2.24 - */ - - -/** - * g_variant_type_is_maybe: - * @type: a #GVariantType - * - * Determines if the given @type is a maybe type. This is true if the - * type string for @type starts with an 'm'. - * - * This function returns %TRUE for any indefinite type for which every - * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for - * example. - * - * Returns: %TRUE if @type is a maybe type - * - * Since 2.24 - */ - - -/** - * g_variant_type_is_subtype_of: - * @type: a #GVariantType - * @supertype: a #GVariantType - * - * Checks if @type is a subtype of @supertype. - * - * This function returns %TRUE if @type is a subtype of @supertype. All - * types are considered to be subtypes of themselves. Aside from that, - * only indefinite types can have subtypes. - * - * Returns: %TRUE if @type is a subtype of @supertype - * - * Since 2.24 - */ - - -/** - * g_variant_type_is_tuple: - * @type: a #GVariantType - * - * Determines if the given @type is a tuple type. This is true if the - * type string for @type starts with a '(' or if @type is - * %G_VARIANT_TYPE_TUPLE. - * - * This function returns %TRUE for any indefinite type for which every - * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for - * example. - * - * Returns: %TRUE if @type is a tuple type - * - * Since 2.24 - */ - - -/** - * g_variant_type_is_variant: - * @type: a #GVariantType - * - * Determines if the given @type is the variant type. - * - * Returns: %TRUE if @type is the variant type - * - * Since 2.24 - */ - - -/** - * g_variant_type_key: - * @type: a dictionary entry #GVariantType - * - * Determines the key type of a dictionary entry type. - * - * This function may only be used with a dictionary entry type. Other - * than the additional restriction, this call is equivalent to - * g_variant_type_first(). - * - * Returns: (transfer none): the key type of the dictionary entry - * - * Since 2.24 - */ - - -/** - * g_variant_type_n_items: - * @type: a tuple or dictionary entry #GVariantType - * - * Determines the number of items contained in a tuple or - * dictionary entry type. - * - * This function may only be used with tuple or dictionary entry types, - * but must not be used with the generic tuple type - * %G_VARIANT_TYPE_TUPLE. - * - * In the case of a dictionary entry type, this function will always - * return 2. - * - * Returns: the number of items in @type - * - * Since 2.24 - */ - - -/** - * g_variant_type_new: - * @type_string: a valid GVariant type string - * - * Creates a new #GVariantType corresponding to the type string given - * by @type_string. It is appropriate to call g_variant_type_free() on - * the return value. - * - * It is a programmer error to call this function with an invalid type - * string. Use g_variant_type_string_is_valid() if you are unsure. - * - * Returns: (transfer full): a new #GVariantType - * Since: 2.24 - */ - - -/** - * g_variant_type_new_array: (constructor) - * @element: a #GVariantType - * - * Constructs the type corresponding to an array of elements of the - * type @type. - * - * It is appropriate to call g_variant_type_free() on the return value. - * - * Returns: (transfer full): a new array #GVariantType - * - * Since 2.24 - */ - - -/** - * g_variant_type_new_dict_entry: (constructor) - * @key: a basic #GVariantType - * @value: a #GVariantType - * - * Constructs the type corresponding to a dictionary entry with a key - * of type @key and a value of type @value. - * - * It is appropriate to call g_variant_type_free() on the return value. - * - * Returns: (transfer full): a new dictionary entry #GVariantType - * - * Since 2.24 - */ - - -/** - * g_variant_type_new_maybe: (constructor) - * @element: a #GVariantType - * - * Constructs the type corresponding to a maybe instance containing - * type @type or Nothing. - * - * It is appropriate to call g_variant_type_free() on the return value. - * - * Returns: (transfer full): a new maybe #GVariantType - * - * Since 2.24 - */ - - -/** - * g_variant_type_new_tuple: - * @items: (array length=length): an array of #GVariantTypes, one for each item - * @length: the length of @items, or -1 - * - * Constructs a new tuple type, from @items. - * - * @length is the number of items in @items, or -1 to indicate that - * @items is %NULL-terminated. - * - * It is appropriate to call g_variant_type_free() on the return value. - * - * Returns: (transfer full): a new tuple #GVariantType - * - * Since 2.24 - */ - - -/** - * g_variant_type_next: - * @type: a #GVariantType from a previous call - * - * Determines the next item type of a tuple or dictionary entry - * type. - * - * @type must be the result of a previous call to - * g_variant_type_first() or g_variant_type_next(). - * - * If called on the key type of a dictionary entry then this call - * returns the value type. If called on the value type of a dictionary - * entry then this call returns %NULL. - * - * For tuples, %NULL is returned when @type is the last item in a tuple. - * - * Returns: (transfer none): the next #GVariantType after @type, or %NULL - * - * Since 2.24 - */ - - -/** - * g_variant_type_peek_string: (skip) - * @type: a #GVariantType - * - * Returns the type string corresponding to the given @type. The - * result is not nul-terminated; in order to determine its length you - * must call g_variant_type_get_string_length(). - * - * To get a nul-terminated string, see g_variant_type_dup_string(). - * - * Returns: the corresponding type string (not nul-terminated) - * - * Since 2.24 - */ - - -/** - * g_variant_type_string_is_valid: - * @type_string: a pointer to any string - * - * Checks if @type_string is a valid GVariant type string. This call is - * equivalent to calling g_variant_type_string_scan() and confirming - * that the following character is a nul terminator. - * - * Returns: %TRUE if @type_string is exactly one valid type string - * - * Since 2.24 - */ - - -/** - * g_variant_type_string_scan: - * @string: a pointer to any string - * @limit: (nullable): the end of @string, or %NULL - * @endptr: (out) (optional): location to store the end pointer, or %NULL - * - * Scan for a single complete and valid GVariant type string in @string. - * The memory pointed to by @limit (or bytes beyond it) is never - * accessed. - * - * If a valid type string is found, @endptr is updated to point to the - * first character past the end of the string that was found and %TRUE - * is returned. - * - * If there is no valid type string starting at @string, or if the type - * string does not end before @limit then %FALSE is returned. - * - * For the simple case of checking if a string is a valid type string, - * see g_variant_type_string_is_valid(). - * - * Returns: %TRUE if a valid type string was found - * Since: 2.24 - */ - - -/** - * g_variant_type_value: - * @type: a dictionary entry #GVariantType - * - * Determines the value type of a dictionary entry type. - * - * This function may only be used with a dictionary entry type. - * - * Returns: (transfer none): the value type of the dictionary entry - * - * Since 2.24 - */ - - -/** - * g_variant_unref: - * @value: a #GVariant - * - * Decreases the reference count of @value. When its reference count - * drops to 0, the memory used by the variant is freed. - * - * Since: 2.24 - */ - - -/** - * g_vasprintf: - * @string: (not optional) (nullable): the return location for the newly-allocated string. - * @format: (not nullable): a standard printf() format string, but notice - * [string precision pitfalls][string-precision] - * @args: the list of arguments to insert in the output. - * - * An implementation of the GNU vasprintf() function which supports - * positional parameters, as specified in the Single Unix Specification. - * This function is similar to g_vsprintf(), except that it allocates a - * string to hold the output, instead of putting the output in a buffer - * you allocate in advance. - * - * The returned value in @string is guaranteed to be non-NULL, unless - * @format contains `%lc` or `%ls` conversions, which can fail if no - * multibyte representation is available for the given character. - * - * `glib/gprintf.h` must be explicitly included in order to use this function. - * - * Returns: the number of bytes printed. - * Since: 2.4 - */ - - -/** - * g_vfprintf: - * @file: (not nullable): the stream to write to. - * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] - * @args: the list of arguments to insert in the output. - * - * An implementation of the standard fprintf() function which supports - * positional parameters, as specified in the Single Unix Specification. - * - * `glib/gprintf.h` must be explicitly included in order to use this function. - * - * Returns: the number of bytes printed. - * Since: 2.2 - */ - - -/** - * g_vprintf: - * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] - * @args: the list of arguments to insert in the output. - * - * An implementation of the standard vprintf() function which supports - * positional parameters, as specified in the Single Unix Specification. - * - * `glib/gprintf.h` must be explicitly included in order to use this function. - * - * Returns: the number of bytes printed. - * Since: 2.2 - */ - - -/** - * g_vsnprintf: - * @string: the buffer to hold the output. - * @n: the maximum number of bytes to produce (including the - * terminating nul character). - * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] - * @args: the list of arguments to insert in the output. - * - * A safer form of the standard vsprintf() function. The output is guaranteed - * to not exceed @n characters (including the terminating nul character), so - * it is easy to ensure that a buffer overflow cannot occur. - * - * See also g_strdup_vprintf(). - * - * In versions of GLib prior to 1.2.3, this function may return -1 if the - * output was truncated, and the truncated string may not be nul-terminated. - * In versions prior to 1.3.12, this function returns the length of the output - * string. - * - * The return value of g_vsnprintf() conforms to the vsnprintf() function - * as standardized in ISO C99. Note that this is different from traditional - * vsnprintf(), which returns the length of the output string. - * - * The format string may contain positional parameters, as specified in - * the Single Unix Specification. - * - * Returns: the number of bytes which would be produced if the buffer - * was large enough. - */ - - -/** - * g_vsprintf: - * @string: the buffer to hold the output. - * @format: a standard printf() format string, but notice - * [string precision pitfalls][string-precision] - * @args: the list of arguments to insert in the output. - * - * An implementation of the standard vsprintf() function which supports - * positional parameters, as specified in the Single Unix Specification. - * - * `glib/gprintf.h` must be explicitly included in order to use this function. - * - * Returns: the number of bytes printed. - * Since: 2.2 - */ - - -/** - * g_wakeup_acknowledge: - * @wakeup: a #GWakeup - * - * Acknowledges receipt of a wakeup signal on @wakeup. - * - * You must call this after @wakeup polls as ready. If not, it will - * continue to poll as ready until you do so. - * - * If you call this function and @wakeup is not signaled, nothing - * happens. - * - * Since: 2.30 - */ - - -/** - * g_wakeup_free: - * @wakeup: a #GWakeup - * - * Frees @wakeup. - * - * You must not currently be polling on the #GPollFD returned by - * g_wakeup_get_pollfd(), or the result is undefined. - */ - - -/** - * g_wakeup_get_pollfd: - * @wakeup: a #GWakeup - * @poll_fd: a #GPollFD - * - * Prepares a @poll_fd such that polling on it will succeed when - * g_wakeup_signal() has been called on @wakeup. - * - * @poll_fd is valid until @wakeup is freed. - * - * Since: 2.30 - */ - - -/** - * g_wakeup_new: - * - * Creates a new #GWakeup. - * - * You should use g_wakeup_free() to free it when you are done. - * - * Returns: a new #GWakeup - * Since: 2.30 - */ - - -/** - * g_wakeup_signal: - * @wakeup: a #GWakeup - * - * Signals @wakeup. - * - * Any future (or present) polling on the #GPollFD returned by - * g_wakeup_get_pollfd() will immediately succeed until such a time as - * g_wakeup_acknowledge() is called. - * - * This function is safe to call from a UNIX signal handler. - * - * Since: 2.30 - */ - - -/** - * g_warn_message: (skip) - * @domain: (nullable): log domain - * @file: file containing the warning - * @line: line number of the warning - * @func: function containing the warning - * @warnexpr: (nullable): expression which failed - * - * Internal function used to print messages from the public g_warn_if_reached() - * and g_warn_if_fail() macros. - */ - - -/** - * g_warning: - * @...: format string, followed by parameters to insert - * into the format string (as with printf()) - * - * A convenience function/macro to log a warning message. The message should - * typically *not* be translated to the user's language. - * - * This is not intended for end user error reporting. Use of #GError is - * preferred for that instead, as it allows calling functions to perform actions - * conditional on the type of error. - * - * Warning messages are intended to be used in the event of unexpected - * external conditions (system misconfiguration, missing files, - * other trusted programs violating protocol, invalid contents in - * trusted files, etc.) - * - * If attempting to deal with programmer errors (for example, incorrect function - * parameters) then you should use %G_LOG_LEVEL_CRITICAL instead. - * - * g_warn_if_reached() and g_warn_if_fail() log at %G_LOG_LEVEL_WARNING. - * - * You can make 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 - * ]| - * - * Any unrelated failures can be skipped over in - * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. - * - * If g_log_default_handler() is used as the log handler function, - * a newline 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_win32_check_windows_version: - * @major: major version of Windows - * @minor: minor version of Windows - * @spver: Windows Service Pack Level, 0 if none - * @os_type: Type of Windows OS - * - * Returns whether the version of the Windows operating system the - * code is running on is at least the specified major, minor and - * service pack versions. See MSDN documentation for the Operating - * System Version. Software that needs even more detailed version and - * feature information should use the Win32 API VerifyVersionInfo() - * directly. - * - * Successive calls of this function can be used for enabling or - * disabling features at run-time for a range of Windows versions, - * as per the VerifyVersionInfo() API documentation. - * - * Returns: %TRUE if the Windows Version is the same or greater than - * the specified major, minor and service pack versions, and - * whether the running Windows is a workstation or server edition - * of Windows, if specifically specified. - * Since: 2.44 - */ - - -/** - * g_win32_error_message: - * @error: error code. - * - * Translate a Win32 error code (as returned by GetLastError() or - * WSAGetLastError()) into the corresponding message. The message is - * either language neutral, or in the thread's language, or the user's - * language, the system's language, or US English (see docs for - * FormatMessage()). The returned string is in UTF-8. It should be - * deallocated with g_free(). - * - * Returns: newly-allocated error message - */ - - -/** - * g_win32_get_command_line: - * - * Gets the command line arguments, on Windows, in the GLib filename - * encoding (ie: UTF-8). - * - * Normally, on Windows, the command line arguments are passed to main() - * in the system codepage encoding. This prevents passing filenames as - * arguments if the filenames contain characters that fall outside of - * this codepage. If such filenames are passed, then substitutions - * will occur (such as replacing some characters with '?'). - * - * GLib's policy of using UTF-8 as a filename encoding on Windows was - * designed to localise the pain of dealing with filenames outside of - * the system codepage to one area: dealing with commandline arguments - * in main(). - * - * As such, most GLib programs should ignore the value of argv passed to - * their main() function and call g_win32_get_command_line() instead. - * This will get the "full Unicode" commandline arguments using - * GetCommandLineW() and convert it to the GLib filename encoding (which - * is UTF-8 on Windows). - * - * The strings returned by this function are suitable for use with - * functions such as g_open() and g_file_new_for_commandline_arg() but - * are not suitable for use with g_option_context_parse(), which assumes - * that its input will be in the system codepage. The return value is - * suitable for use with g_option_context_parse_strv(), however, which - * is a better match anyway because it won't leak memory. - * - * Unlike argv, the returned value is a normal strv and can (and should) - * be freed with g_strfreev() when no longer needed. - * - * Returns: (transfer full): the commandline arguments in the GLib - * filename encoding (ie: UTF-8) - * Since: 2.40 - */ - - -/** - * g_win32_get_package_installation_directory: - * @package: (nullable): You should pass %NULL for this. - * @dll_name: (nullable): The name of a DLL that a package provides in UTF-8, or %NULL. - * - * Try to determine the installation directory for a software package. - * - * This function is deprecated. Use - * g_win32_get_package_installation_directory_of_module() instead. - * - * The use of @package is deprecated. You should always pass %NULL. A - * warning is printed if non-NULL is passed as @package. - * - * The original intended use of @package was for a short identifier of - * the package, typically the same identifier as used for - * `GETTEXT_PACKAGE` in software configured using GNU - * autotools. The function first looks in the Windows Registry for the - * value `#InstallationDirectory` in the key - * `#HKLM\Software\@package`, and if that value - * exists and is a string, returns that. - * - * It is strongly recommended that packagers of GLib-using libraries - * for Windows do not store installation paths in the Registry to be - * used by this function as that interfers with having several - * parallel installations of the library. Enabling multiple - * installations of different versions of some GLib-using library, or - * GLib itself, is desirable for various reasons. - * - * For this reason it is recommended to always pass %NULL as - * @package to this function, to avoid the temptation to use the - * Registry. In version 2.20 of GLib the @package parameter - * will be ignored and this function won't look in the Registry at all. - * - * If @package is %NULL, or the above value isn't found in the - * Registry, but @dll_name is non-%NULL, it should name a DLL loaded - * into the current process. Typically that would be the name of the - * DLL calling this function, looking for its installation - * directory. The function then asks Windows what directory that DLL - * was loaded from. If that directory's last component is "bin" or - * "lib", the parent directory is returned, otherwise the directory - * itself. If that DLL isn't loaded, the function proceeds as if - * @dll_name was %NULL. - * - * If both @package and @dll_name are %NULL, the directory from where - * the main executable of the process was loaded is used instead in - * the same way as above. - * - * Returns: a string containing the installation directory for - * @package. The string is in the GLib file name encoding, - * i.e. UTF-8. The return value should be freed with g_free() when not - * needed any longer. If the function fails %NULL is returned. - * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to - * g_win32_get_package_installation_directory_of_module() instead. - */ - - -/** - * g_win32_get_package_installation_directory_of_module: - * @hmodule: (nullable): The Win32 handle for a DLL loaded into the current process, or %NULL - * - * This function tries to determine the installation directory of a - * software package based on the location of a DLL of the software - * package. - * - * @hmodule should be the handle of a loaded DLL or %NULL. The - * function looks up the directory that DLL was loaded from. If - * @hmodule is NULL, the directory the main executable of the current - * process is looked up. If that directory's last component is "bin" - * or "lib", its parent directory is returned, otherwise the directory - * itself. - * - * It thus makes sense to pass only the handle to a "public" DLL of a - * software package to this function, as such DLLs typically are known - * to be installed in a "bin" or occasionally "lib" subfolder of the - * installation folder. DLLs that are of the dynamically loaded module - * or plugin variety are often located in more private locations - * deeper down in the tree, from which it is impossible for GLib to - * deduce the root of the package installation. - * - * The typical use case for this function is to have a DllMain() that - * saves the handle for the DLL. Then when code in the DLL needs to - * construct names of files in the installation tree it calls this - * function passing the DLL handle. - * - * Returns: a string containing the guessed installation directory for - * the software package @hmodule is from. The string is in the GLib - * file name encoding, i.e. UTF-8. The return value should be freed - * with g_free() when not needed any longer. If the function fails - * %NULL is returned. - * Since: 2.16 - */ - - -/** - * g_win32_get_package_installation_subdirectory: - * @package: (nullable): You should pass %NULL for this. - * @dll_name: (nullable): The name of a DLL that a package provides, in UTF-8, or %NULL. - * @subdir: A subdirectory of the package installation directory, also in UTF-8 - * - * This function is deprecated. Use - * g_win32_get_package_installation_directory_of_module() and - * g_build_filename() instead. - * - * Returns a newly-allocated string containing the path of the - * subdirectory @subdir in the return value from calling - * g_win32_get_package_installation_directory() with the @package and - * @dll_name parameters. See the documentation for - * g_win32_get_package_installation_directory() for more details. In - * particular, note that it is deprecated to pass anything except NULL - * as @package. - * - * Returns: a string containing the complete path to @subdir inside - * the installation directory of @package. The returned string is in - * the GLib file name encoding, i.e. UTF-8. The return value should be - * freed with g_free() when no longer needed. If something goes wrong, - * %NULL is returned. - * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to - * g_win32_get_package_installation_directory_of_module() instead, and - * then construct a subdirectory pathname with g_build_filename(). - */ - - -/** - * g_win32_get_windows_version: - * - * This function is deprecated. Use - * g_win32_check_windows_version() instead. - * - * Returns version information for the Windows operating system the - * code is running on. See MSDN documentation for the GetVersion() - * function. To summarize, the most significant bit is one on Win9x, - * and zero on NT-based systems. Since version 2.14, GLib works only - * on NT-based systems, so checking whether your are running on Win9x - * in your own software is moot. The least significant byte is 4 on - * Windows NT 4, and 5 on Windows XP. Software that needs really - * detailed version and feature information should use Win32 API like - * GetVersionEx() and VerifyVersionInfo(). - * - * Returns: The version information. - * Deprecated: 2.44: Be aware that for Windows 8.1 and Windows Server - * 2012 R2 and later, this will return 62 unless the application is - * manifested for Windows 8.1/Windows Server 2012 R2, for example. - * MSDN stated that GetVersion(), which is used here, is subject to - * further change or removal after Windows 8.1. - */ - - -/** - * g_win32_getlocale: - * - * The setlocale() function in the Microsoft C library uses locale - * names of the form "English_United States.1252" etc. We want the - * UNIXish standard form "en_US", "zh_TW" etc. This function gets the - * current thread locale from Windows - without any encoding info - - * and returns it as a string of the above form for use in forming - * file names etc. The returned string should be deallocated with - * g_free(). - * - * Returns: newly-allocated locale name. - */ - - -/** - * g_win32_locale_filename_from_utf8: - * @utf8filename: a UTF-8 encoded filename. - * - * Converts a filename from UTF-8 to the system codepage. - * - * On NT-based Windows, on NTFS file systems, file names are in - * Unicode. It is quite possible that Unicode file names contain - * characters not representable in the system codepage. (For instance, - * Greek or Cyrillic characters on Western European or US Windows - * installations, or various less common CJK characters on CJK Windows - * installations.) - * - * In such a case, and if the filename refers to an existing file, and - * the file system stores alternate short (8.3) names for directory - * entries, the short form of the filename is returned. Note that the - * "short" name might in fact be longer than the Unicode name if the - * Unicode name has very short pathname components containing - * non-ASCII characters. If no system codepage name for the file is - * possible, %NULL is returned. - * - * The return value is dynamically allocated and should be freed with - * g_free() when no longer needed. - * - * Returns: The converted filename, or %NULL on conversion - * failure and lack of short names. - * Since: 2.8 - */ - - -/** - * g_win32_readlink_utf8: - * @filename: (type filename): a pathname in UTF-8 - * @buf: (array length=buf_size): a buffer to receive the reparse point - * target path. Mutually-exclusive - * with @alloc_buf. - * @buf_size: size of the @buf, in bytes - * @alloc_buf: points to a location where internally-allocated buffer - * pointer will be written. That buffer receives the - * link data. Mutually-exclusive with @buf. - * @terminate: ensures that the buffer is NUL-terminated if - * it isn't already. If %FALSE, the returned string - * might not be NUL-terminated (depends entirely on - * what the contents of the filesystem are). - * - * Tries to read the reparse point indicated by @filename, filling - * @buf or @alloc_buf with the path that the reparse point redirects to. - * The path will be UTF-8-encoded, and an extended path prefix - * or a NT object manager prefix will be removed from it, if - * possible, but otherwise the path is returned as-is. Specifically, - * it could be a "\\\\Volume{GUID}\\" path. It also might use - * backslashes as path separators. - * - * Returns: -1 on error (sets errno), 0 if there's no (recognizable) - * path in the reparse point (@alloc_buf will not be allocated in that case, - * and @buf will be left unmodified), - * or the number of bytes placed into @buf otherwise, - * including NUL-terminator (if present or if @terminate is TRUE). - * The buffer returned via @alloc_buf should be freed with g_free(). - * Since: 2.60 - */ - - -/** - * gatomicrefcount: - * - * A type for implementing atomic reference count semantics. - * - * Use g_atomic_ref_count_init() to initialize it; g_atomic_ref_count_inc() - * to increase the counter, and g_atomic_ref_count_dec() to decrease it. - * - * It is safe to use #gatomicrefcount if you're expecting to operate on the - * reference counter from multiple threads. - * - * See also: #grefcount - * - * Since: 2.58 - */ - - -/** - * gboolean: - * - * A standard boolean type. - * Variables of this type should only contain the value - * %TRUE or %FALSE. - * - * Never directly compare the contents of a #gboolean variable with the values - * %TRUE or %FALSE. Use `if (condition)` to check a #gboolean is "true", instead - * of `if (condition == TRUE)`. Likewise use `if (!condition)` to check a - * #gboolean is "false". - * - * There is no validation when assigning to a #gboolean variable and so it could - * contain any value represented by a #gint. This is why the use of `if - * (condition)` is recommended. All non-zero values in C evaluate to "true". - */ - - -/** - * gchar: - * - * Corresponds to the standard C char type. - */ - - -/** - * gconstpointer: - * - * An untyped pointer to constant data. - * The data pointed to should not be changed. - * - * This is typically used in function prototypes to indicate - * that the data pointed to will not be altered by the function. - */ - - -/** - * gdouble: - * - * Corresponds to the standard C double type. - * Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE. - */ - - -/** - * gfloat: - * - * Corresponds to the standard C float type. - * Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT. - */ - - -/** - * gint: - * - * Corresponds to the standard C int type. - * Values of this type can range from #G_MININT to #G_MAXINT. - */ - - -/** - * gint16: - * - * A signed integer guaranteed to be 16 bits on all platforms. - * Values of this type can range from #G_MININT16 (= -32,768) to - * #G_MAXINT16 (= 32,767). - * - * To print or scan values of this type, use - * %G_GINT16_MODIFIER and/or %G_GINT16_FORMAT. - */ - - -/** - * gint32: - * - * A signed integer guaranteed to be 32 bits on all platforms. - * Values of this type can range from #G_MININT32 (= -2,147,483,648) - * to #G_MAXINT32 (= 2,147,483,647). - * - * To print or scan values of this type, use - * %G_GINT32_MODIFIER and/or %G_GINT32_FORMAT. - */ - - -/** - * gint64: - * - * A signed integer guaranteed to be 64 bits on all platforms. - * Values of this type can range from #G_MININT64 - * (= -9,223,372,036,854,775,808) to #G_MAXINT64 - * (= 9,223,372,036,854,775,807). - * - * To print or scan values of this type, use - * %G_GINT64_MODIFIER and/or %G_GINT64_FORMAT. - */ - - -/** - * gint8: - * - * A signed integer guaranteed to be 8 bits on all platforms. - * Values of this type can range from #G_MININT8 (= -128) to - * #G_MAXINT8 (= 127). - */ - - -/** - * gintptr: - * - * Corresponds to the C99 type intptr_t, - * a signed integer type that can hold any pointer. - * - * To print or scan values of this type, use - * %G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT. - * - * Since: 2.18 - */ - - -/** - * glib__private__: - * @arg: Do not use this argument - * - * Do not call this function; it is used to share private - * API between glib, gobject, and gio. - */ - - -/** - * glib_binary_age: - * - * The binary age of the GLib library. - * Defines how far back backwards compatibility reaches. - * - * An integer variable exported from the library linked - * against at application run time. - */ - - -/** - * glib_check_version: - * @required_major: the required major version - * @required_minor: the required minor version - * @required_micro: the required micro version - * - * Checks that the GLib library in use is compatible with the - * given version. - * - * Generally you would pass in the constants %GLIB_MAJOR_VERSION, - * %GLIB_MINOR_VERSION, %GLIB_MICRO_VERSION as the three arguments - * to this function; that produces a check that the library in use - * is compatible with the version of GLib the application or module - * was compiled against. - * - * Compatibility is defined by two things: first the version - * of the running library is newer than the version - * `@required_major.required_minor.@required_micro`. Second - * the running library must be binary compatible with the - * version `@required_major.@required_minor.@required_micro` - * (same major version.) - * - * Returns: (transfer none) (nullable): %NULL if the GLib library is - * compatible with the given version, or a string describing the - * version mismatch. The returned string is owned by GLib and must - * not be modified or freed. - * Since: 2.6 - */ - - -/** - * glib_gettext: - * @str: The string to be translated - * - * Returns the translated string from the glib translations. - * This is an internal function and should only be used by - * the internals of glib (such as libgio). - * - * Returns: the translation of @str to the current locale - */ - - -/** - * glib_interface_age: - * - * The interface age of the GLib library. - * Defines how far back the API has last been extended. - * - * An integer variable exported from the library linked - * against at application run time. - */ - - -/** - * glib_major_version: - * - * The major version of the GLib library. - * - * An integer variable exported from the library linked - * against at application run time. - */ - - -/** - * glib_mem_profiler_table: - * - * Used to be a #GMemVTable containing profiling variants of the memory - * allocation functions, but this variable shouldn't be modified anymore. - * - * Deprecated: 2.46: Use other memory profiling tools instead - */ - - -/** - * glib_micro_version: - * - * The micro version number of the GLib library. - * - * An integer variable exported from the library linked - * against at application run time. - */ - - -/** - * glib_minor_version: - * - * The minor version number of the GLib library. - * - * An integer variable exported from the library linked - * against at application run time. - */ - - -/** - * glib_pgettext: - * @msgctxtid: a combined message context and message id, separated - * by a \004 character - * @msgidoffset: the offset of the message id in @msgctxid - * - * This function is a variant of glib_gettext() which supports - * a disambiguating message context. See g_dpgettext() for full - * details. - * - * This is an internal function and should only be used by - * the internals of glib (such as libgio). - * - * Returns: the translation of @str to the current locale - */ - - -/** - * glong: - * - * Corresponds to the standard C long type. - * Values of this type can range from #G_MINLONG to #G_MAXLONG. - */ - - -/** - * goffset: - * - * A signed integer type that is used for file offsets, - * corresponding to the POSIX type `off_t` as if compiling with - * `_FILE_OFFSET_BITS` set to 64. #goffset is always 64 bits wide, even on - * 32-bit architectures. - * Values of this type can range from #G_MINOFFSET to - * #G_MAXOFFSET. - * - * To print or scan values of this type, use - * %G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT. - * - * Since: 2.14 - */ - - -/** - * gpointer: - * - * An untyped pointer. - * #gpointer looks better and is easier to use than void*. - */ - - -/** - * grefcount: - * - * A type for implementing non-atomic reference count semantics. - * - * Use g_ref_count_init() to initialize it; g_ref_count_inc() to - * increase the counter, and g_ref_count_dec() to decrease it. - * - * It is safe to use #grefcount only if you're expecting to operate - * on the reference counter from a single thread. It is entirely up - * to you to ensure that all reference count changes happen in the - * same thread. - * - * See also: #gatomicrefcount - * - * Since: 2.58 - */ - - -/** - * gshort: - * - * Corresponds to the standard C short type. - * Values of this type can range from #G_MINSHORT to #G_MAXSHORT. - */ - - -/** - * gsize: - * - * An unsigned integer type of the result of the sizeof operator, - * corresponding to the size_t type defined in C99. - * This type is wide enough to hold the numeric value of a pointer, - * so it is usually 32 bit wide on a 32-bit platform and 64 bit wide - * on a 64-bit platform. Values of this type can range from 0 to - * #G_MAXSIZE. - * - * To print or scan values of this type, use - * %G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT. - */ - - -/** - * gssize: - * - * A signed variant of #gsize, corresponding to the - * ssize_t defined on most platforms. - * Values of this type can range from #G_MINSSIZE - * to #G_MAXSSIZE. - * - * To print or scan values of this type, use - * %G_GSSIZE_MODIFIER and/or %G_GSSIZE_FORMAT. - */ - - -/** - * guchar: - * - * Corresponds to the standard C unsigned char type. - */ - - -/** - * guint: - * - * Corresponds to the standard C unsigned int type. - * Values of this type can range from 0 to #G_MAXUINT. - */ - - -/** - * guint16: - * - * An unsigned integer guaranteed to be 16 bits on all platforms. - * Values of this type can range from 0 to #G_MAXUINT16 (= 65,535). - * - * To print or scan values of this type, use - * %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT. - */ - - -/** - * guint32: - * - * An unsigned integer guaranteed to be 32 bits on all platforms. - * Values of this type can range from 0 to #G_MAXUINT32 (= 4,294,967,295). - * - * To print or scan values of this type, use - * %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT. - */ - - -/** - * guint64: - * - * An unsigned integer guaranteed to be 64-bits on all platforms. - * Values of this type can range from 0 to #G_MAXUINT64 - * (= 18,446,744,073,709,551,615). - * - * To print or scan values of this type, use - * %G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT. - */ - - -/** - * guint8: - * - * An unsigned integer guaranteed to be 8 bits on all platforms. - * Values of this type can range from 0 to #G_MAXUINT8 (= 255). - */ - - -/** - * guintptr: - * - * Corresponds to the C99 type uintptr_t, - * an unsigned integer type that can hold any pointer. - * - * To print or scan values of this type, use - * %G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT. - * - * Since: 2.18 - */ - - -/** - * gulong: - * - * Corresponds to the standard C unsigned long type. - * Values of this type can range from 0 to #G_MAXULONG. - */ - - -/** - * gushort: - * - * Corresponds to the standard C unsigned short type. - * Values of this type can range from 0 to #G_MAXUSHORT. - */ - - - -/************************************************************/ -/* THIS FILE IS GENERATED DO NOT EDIT */ -/************************************************************/ diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c deleted file mode 100644 index 988a8b0f..00000000 --- a/gir/gmodule-2.0.c +++ /dev/null @@ -1,289 +0,0 @@ -/************************************************************/ -/* THIS FILE IS GENERATED DO NOT EDIT */ -/************************************************************/ - -/** - * GModule: - * - * The #GModule struct is an opaque data structure to represent a - * [dynamically-loaded module][glib-Dynamic-Loading-of-Modules]. - * It should only be accessed via the following functions. - */ - - -/** - * GModuleCheckInit: - * @module: the #GModule corresponding to the module which has just been loaded - * - * Specifies the type of the module initialization function. - * If a module contains a function named g_module_check_init() it is called - * automatically when the module is loaded. It is passed the #GModule structure - * and should return %NULL on success or a string describing the initialization - * error. - * - * Returns: %NULL on success, or a string describing the initialization error - */ - - -/** - * GModuleUnload: - * @module: the #GModule about to be unloaded - * - * Specifies the type of the module function called when it is unloaded. - * If a module contains a function named g_module_unload() it is called - * automatically when the module is unloaded. - * It is passed the #GModule structure. - */ - - -/** - * G_MODULE_ERROR: - * - * The error domain of the #GModule API. - * - * Since: 2.70 - */ - - -/** - * G_MODULE_EXPORT: - * - * Used to declare functions exported by libraries or modules. - * - * When compiling for Windows, it marks the symbol as `dllexport`. - * - * When compiling for Linux and Unices, it marks the symbol as having `default` - * visibility. This is no-op unless the code is being compiled with a - * non-default - * [visibility flag](https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#index-fvisibility-1260) - * such as `hidden`. - */ - - -/** - * G_MODULE_IMPORT: - * - * Used to declare functions imported from modules. - */ - - -/** - * G_MODULE_SUFFIX: - * - * Expands to the proper shared library suffix for the current platform - * without the leading dot. For most Unices and Linux this is "so", and - * for Windows this is "dll". - */ - - -/** - * SECTION:modules - * @title: Dynamic Loading of Modules - * @short_description: portable method for dynamically loading 'plug-ins' - * - * These functions provide a portable way to dynamically load object files - * (commonly known as 'plug-ins'). The current implementation supports all - * systems that provide an implementation of dlopen() (e.g. Linux/Sun), as - * well as Windows platforms via DLLs. - * - * A program which wants to use these functions must be linked to the - * libraries output by the command `pkg-config --libs gmodule-2.0`. - * - * To use them you must first determine whether dynamic loading - * is supported on the platform by calling g_module_supported(). - * If it is, you can open a module with g_module_open(), - * find the module's symbols (e.g. function names) with g_module_symbol(), - * and later close the module with g_module_close(). - * g_module_name() will return the file name of a currently opened module. - * - * If any of the above functions fail, the error status can be found with - * g_module_error(). - * - * The #GModule implementation features reference counting for opened modules, - * and supports hook functions within a module which are called when the - * module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload). - * - * If your module introduces static data to common subsystems in the running - * program, e.g. through calling - * `g_quark_from_static_string ("my-module-stuff")`, - * it must ensure that it is never unloaded, by calling g_module_make_resident(). - * - * Example: Calling a function defined in a GModule - * |[<!-- language="C" --> - * // the function signature for 'say_hello' - * typedef void (* SayHelloFunc) (const char *message); - * - * gboolean - * just_say_hello (const char *filename, GError **error) - * { - * SayHelloFunc say_hello; - * GModule *module; - * - * module = g_module_open (filename, G_MODULE_BIND_LAZY); - * if (!module) - * { - * g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH, - * "%s", g_module_error ()); - * return FALSE; - * } - * - * if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello)) - * { - * g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN, - * "%s: %s", filename, g_module_error ()); - * if (!g_module_close (module)) - * g_warning ("%s: %s", filename, g_module_error ()); - * return FALSE; - * } - * - * if (say_hello == NULL) - * { - * g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN, - * "symbol say_hello is NULL"); - * if (!g_module_close (module)) - * g_warning ("%s: %s", filename, g_module_error ()); - * return FALSE; - * } - * - * // call our function in the module - * say_hello ("Hello world!"); - * - * if (!g_module_close (module)) - * g_warning ("%s: %s", filename, g_module_error ()); - * return TRUE; - * } - * ]| - */ - - -/** - * g_module_build_path: - * @directory: (nullable): the directory where the module is. This can be - * %NULL or the empty string to indicate that the standard platform-specific - * directories will be used, though that is not recommended - * @module_name: the name of the module - * - * A portable way to build the filename of a module. The platform-specific - * prefix and suffix are added to the filename, if needed, and the result - * is added to the directory, using the correct separator character. - * - * The directory should specify the directory where the module can be found. - * It can be %NULL or an empty string to indicate that the module is in a - * standard platform-specific directory, though this is not recommended - * since the wrong module may be found. - * - * For example, calling g_module_build_path() on a Linux system with a - * @directory of `/lib` and a @module_name of "mylibrary" will return - * `/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the - * directory it will return `\Windows\mylibrary.dll`. - * - * Returns: the complete path of the module, including the standard library - * prefix and suffix. This should be freed when no longer needed - */ - - -/** - * g_module_close: - * @module: a #GModule to close - * - * Closes a module. - * - * Returns: %TRUE on success - */ - - -/** - * g_module_error: - * - * Gets a string describing the last module error. - * - * Returns: a string describing the last module error - */ - - -/** - * g_module_make_resident: - * @module: a #GModule to make permanently resident - * - * Ensures that a module will never be unloaded. - * Any future g_module_close() calls on the module will be ignored. - */ - - -/** - * g_module_name: - * @module: a #GModule - * - * Returns the filename that the module was opened with. - * - * If @module refers to the application itself, "main" is returned. - * - * Returns: (transfer none): the filename of the module - */ - - -/** - * g_module_open: - * @file_name: (nullable): the name of the file containing the module, or %NULL - * to obtain a #GModule representing the main program itself - * @flags: the flags used for opening the module. This can be the - * logical OR of any of the #GModuleFlags. - * - * A thin wrapper function around g_module_open_full() - * - * Returns: a #GModule on success, or %NULL on failure - */ - - -/** - * g_module_open_full: - * @file_name: (nullable): the name of the file containing the module, or %NULL - * to obtain a #GModule representing the main program itself - * @flags: the flags used for opening the module. This can be the - * logical OR of any of the #GModuleFlags - * @error: #GError. - * - * Opens a module. If the module has already been opened, - * its reference count is incremented. - * - * First of all g_module_open_full() tries to open @file_name as a module. - * If that fails and @file_name has the ".la"-suffix (and is a libtool - * archive) it tries to open the corresponding module. If that fails - * and it doesn't have the proper module suffix for the platform - * (#G_MODULE_SUFFIX), this suffix will be appended and the corresponding - * module will be opened. If that fails and @file_name doesn't have the - * ".la"-suffix, this suffix is appended and g_module_open_full() tries to open - * the corresponding module. If eventually that fails as well, %NULL is - * returned. - * - * Returns: a #GModule on success, or %NULL on failure - * Since: 2.70 - */ - - -/** - * g_module_supported: - * - * Checks if modules are supported on the current platform. - * - * Returns: %TRUE if modules are supported - */ - - -/** - * g_module_symbol: - * @module: a #GModule - * @symbol_name: the name of the symbol to find - * @symbol: (out): returns the pointer to the symbol value - * - * Gets a symbol pointer from a module, such as one exported - * by #G_MODULE_EXPORT. Note that a valid symbol can be %NULL. - * - * Returns: %TRUE on success - */ - - - -/************************************************************/ -/* THIS FILE IS GENERATED DO NOT EDIT */ -/************************************************************/ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c deleted file mode 100644 index 8bfce427..00000000 --- a/gir/gobject-2.0.c +++ /dev/null @@ -1,7336 +0,0 @@ -/************************************************************/ -/* THIS FILE IS GENERATED DO NOT EDIT */ -/************************************************************/ - -/** - * GBinding:flags: - * - * Flags to be used to control the #GBinding - * - * Since: 2.26 - */ - - -/** - * GBinding:source: - * - * The #GObject that should be used as the source of the binding - * - * Since: 2.26 - */ - - -/** - * GBinding:source-property: - * - * The name of the property of #GBinding:source that should be used - * as the source of the binding. - * - * This should be in [canonical form][canonical-parameter-names] to get the - * best performance. - * - * Since: 2.26 - */ - - -/** - * GBinding:target: - * - * The #GObject that should be used as the target of the binding - * - * Since: 2.26 - */ - - -/** - * GBinding:target-property: - * - * The name of the property of #GBinding:target that should be used - * as the target of the binding. - * - * This should be in [canonical form][canonical-parameter-names] to get the - * best performance. - * - * Since: 2.26 - */ - - -/** - * GObject::notify: - * @gobject: the object which received the signal. - * @pspec: the #GParamSpec of the property which changed. - * - * The notify signal is emitted on an object when one of its properties has - * its value set through g_object_set_property(), g_object_set(), et al. - * - * Note that getting this signal doesn’t itself guarantee that the value of - * the property has actually changed. When it is emitted is determined by the - * derived GObject class. If the implementor did not create the property with - * %G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results - * in ::notify being emitted, even if the new value is the same as the old. - * If they did pass %G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only - * when they explicitly call g_object_notify() or g_object_notify_by_pspec(), - * and common practice is to do that only when the value has actually changed. - * - * This signal is typically used to obtain change notification for a - * single property, by specifying the property name as a detail in the - * g_signal_connect() call, like this: - * - * |[<!-- language="C" --> - * g_signal_connect (text_view->buffer, "notify::paste-target-list", - * G_CALLBACK (gtk_text_view_target_list_notify), - * text_view) - * ]| - * - * It is important to note that you must use - * [canonical parameter names][canonical-parameter-names] as - * detail strings for the notify signal. - */ - - -/** - * GParamSpecPool: - * - * A #GParamSpecPool maintains a collection of #GParamSpecs which can be - * quickly accessed by owner and name. - * - * The implementation of the #GObject property system uses such a pool to - * store the #GParamSpecs of the properties all object types. - */ - - -/** - * GWeakRef: - * - * A structure containing a weak reference to a #GObject. - * - * A `GWeakRef` can either be empty (i.e. point to %NULL), or point to an - * object for as long as at least one "strong" reference to that object - * exists. Before the object's #GObjectClass.dispose method is called, - * every #GWeakRef associated with becomes empty (i.e. points to %NULL). - * - * Like #GValue, #GWeakRef can be statically allocated, stack- or - * heap-allocated, or embedded in larger structures. - * - * Unlike g_object_weak_ref() and g_object_add_weak_pointer(), this weak - * reference is thread-safe: converting a weak pointer to a reference is - * atomic with respect to invalidation of weak pointers to destroyed - * objects. - * - * If the object's #GObjectClass.dispose method results in additional - * references to the object being held, any #GWeakRefs taken - * before it was disposed will continue to point to %NULL. If - * #GWeakRefs are taken after the object is disposed and - * re-referenced, they will continue to point to it until its refcount - * goes back to zero, at which point they too will be invalidated. - */ - - -/** - * SECTION:enumerations_flags - * @short_description: Enumeration and flags types - * @title: Enumeration and Flag Types - * @see_also: #GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(), - * g_param_spec_flags() - * - * The GLib type system provides fundamental types for enumeration and - * flags types. (Flags types are like enumerations, but allow their - * values to be combined by bitwise or). A registered enumeration or - * flags type associates a name and a nickname with each allowed - * value, and the methods g_enum_get_value_by_name(), - * g_enum_get_value_by_nick(), g_flags_get_value_by_name() and - * g_flags_get_value_by_nick() can look up values by their name or - * nickname. When an enumeration or flags type is registered with the - * GLib type system, it can be used as value type for object - * properties, using g_param_spec_enum() or g_param_spec_flags(). - * - * GObject ships with a utility called [glib-mkenums][glib-mkenums], - * that can construct suitable type registration functions from C enumeration - * definitions. - * - * Example of how to get a string representation of an enum value: - * |[<!-- language="C" --> - * GEnumClass *enum_class; - * GEnumValue *enum_value; - * - * enum_class = g_type_class_ref (MAMAN_TYPE_MY_ENUM); - * enum_value = g_enum_get_value (enum_class, MAMAN_MY_ENUM_FOO); - * - * g_print ("Name: %s\n", enum_value->value_name); - * - * g_type_class_unref (enum_class); - * ]| - */ - - -/** - * SECTION:gbinding - * @Title: GBinding - * @Short_Description: Bind two object properties - * - * #GBinding is the representation of a binding between a property on a - * #GObject instance (or source) and another property on another #GObject - * instance (or target). - * - * Whenever the source property changes, the same value is applied to the - * target property; for instance, the following binding: - * - * |[<!-- language="C" --> - * g_object_bind_property (object1, "property-a", - * object2, "property-b", - * G_BINDING_DEFAULT); - * ]| - * - * will cause the property named "property-b" of @object2 to be updated - * every time g_object_set() or the specific accessor changes the value of - * the property "property-a" of @object1. - * - * It is possible to create a bidirectional binding between two properties - * of two #GObject instances, so that if either property changes, the - * other is updated as well, for instance: - * - * |[<!-- language="C" --> - * g_object_bind_property (object1, "property-a", - * object2, "property-b", - * G_BINDING_BIDIRECTIONAL); - * ]| - * - * will keep the two properties in sync. - * - * It is also possible to set a custom transformation function (in both - * directions, in case of a bidirectional binding) to apply a custom - * transformation from the source value to the target value before - * applying it; for instance, the following binding: - * - * |[<!-- language="C" --> - * g_object_bind_property_full (adjustment1, "value", - * adjustment2, "value", - * G_BINDING_BIDIRECTIONAL, - * celsius_to_fahrenheit, - * fahrenheit_to_celsius, - * NULL, NULL); - * ]| - * - * will keep the "value" property of the two adjustments in sync; the - * @celsius_to_fahrenheit function will be called whenever the "value" - * property of @adjustment1 changes and will transform the current value - * of the property before applying it to the "value" property of @adjustment2. - * - * Vice versa, the @fahrenheit_to_celsius function will be called whenever - * the "value" property of @adjustment2 changes, and will transform the - * current value of the property before applying it to the "value" property - * of @adjustment1. - * - * Note that #GBinding does not resolve cycles by itself; a cycle like - * - * |[ - * object1:propertyA -> object2:propertyB - * object2:propertyB -> object3:propertyC - * object3:propertyC -> object1:propertyA - * ]| - * - * might lead to an infinite loop. The loop, in this particular case, - * can be avoided if the objects emit the #GObject::notify signal only - * if the value has effectively been changed. A binding is implemented - * using the #GObject::notify signal, so it is susceptible to all the - * various ways of blocking a signal emission, like g_signal_stop_emission() - * or g_signal_handler_block(). - * - * A binding will be severed, and the resources it allocates freed, whenever - * either one of the #GObject instances it refers to are finalized, or when - * the #GBinding instance loses its last reference. - * - * Bindings for languages with garbage collection can use - * g_binding_unbind() to explicitly release a binding between the source - * and target properties, instead of relying on the last reference on the - * binding, source, and target instances to drop. - * - * #GBinding is available since GObject 2.26 - */ - - -/** - * SECTION:gboxed - * @short_description: A mechanism to wrap opaque C structures registered - * by the type system - * @see_also: #GParamSpecBoxed, g_param_spec_boxed() - * @title: Boxed Types - * - * #GBoxed is a generic wrapper mechanism for arbitrary C structures. - * - * The only thing the type system needs to know about the structures is how to - * copy them (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc); - * beyond that, they are treated as opaque chunks of memory. - * - * Boxed types are useful for simple value-holder structures like rectangles or - * points. They can also be used for wrapping structures defined in non-#GObject - * based libraries. They allow arbitrary structures to be handled in a uniform - * way, allowing uniform copying (or referencing) and freeing (or unreferencing) - * of them, and uniform representation of the type of the contained structure. - * In turn, this allows any type which can be boxed to be set as the data in a - * #GValue, which allows for polymorphic handling of a much wider range of data - * types, and hence usage of such types as #GObject property values. - * - * #GBoxed is designed so that reference counted types can be boxed. Use the - * type’s ‘ref’ function as the #GBoxedCopyFunc, and its ‘unref’ function as the - * #GBoxedFreeFunc. For example, for #GBytes, the #GBoxedCopyFunc is - * g_bytes_ref(), and the #GBoxedFreeFunc is g_bytes_unref(). - */ - - -/** - * SECTION:gclosure - * @short_description: Functions as first-class objects - * @title: Closures - * - * A #GClosure represents a callback supplied by the programmer. - * - * It will generally comprise a function of some kind and a marshaller - * used to call it. It is the responsibility of the marshaller to - * convert the arguments for the invocation from #GValues into - * a suitable form, perform the callback on the converted arguments, - * and transform the return value back into a #GValue. - * - * In the case of C programs, a closure usually just holds a pointer - * to a function and maybe a data argument, and the marshaller - * converts between #GValue and native C types. The GObject - * library provides the #GCClosure type for this purpose. Bindings for - * other languages need marshallers which convert between #GValues - * and suitable representations in the runtime of the language in - * order to use functions written in that language as callbacks. Use - * g_closure_set_marshal() to set the marshaller on such a custom - * closure implementation. - * - * Within GObject, closures play an important role in the - * implementation of signals. When a signal is registered, the - * @c_marshaller argument to g_signal_new() specifies the default C - * marshaller for any closure which is connected to this - * signal. GObject provides a number of C marshallers for this - * purpose, see the g_cclosure_marshal_*() functions. Additional C - * marshallers can be generated with the [glib-genmarshal][glib-genmarshal] - * utility. Closures can be explicitly connected to signals with - * g_signal_connect_closure(), but it usually more convenient to let - * GObject create a closure automatically by using one of the - * g_signal_connect_*() functions which take a callback function/user - * data pair. - * - * Using closures has a number of important advantages over a simple - * callback function/data pointer combination: - * - * - Closures allow the callee to get the types of the callback parameters, - * which means that language bindings don't have to write individual glue - * for each callback type. - * - * - The reference counting of #GClosure makes it easy to handle reentrancy - * right; if a callback is removed while it is being invoked, the closure - * and its parameters won't be freed until the invocation finishes. - * - * - g_closure_invalidate() and invalidation notifiers allow callbacks to be - * automatically removed when the objects they point to go away. - */ - - -/** - * SECTION:generic_values - * @short_description: A polymorphic type that can hold values of any - * other type - * @see_also: The fundamental types which all support #GValue - * operations and thus can be used as a type initializer for - * g_value_init() are defined by a separate interface. See the - * [standard values API][gobject-Standard-Parameter-and-Value-Types] - * for details - * @title: Generic values - * - * The #GValue structure is basically a variable container that consists - * of a type identifier and a specific value of that type. - * - * The type identifier within a #GValue structure always determines the - * type of the associated value. - * - * To create an undefined #GValue structure, simply create a zero-filled - * #GValue structure. To initialize the #GValue, use the g_value_init() - * function. A #GValue cannot be used until it is initialized. Before - * destruction you must always use g_value_unset() to make sure allocated - * memory is freed. - * - * The basic type operations (such as freeing and copying) are determined - * by the #GTypeValueTable associated with the type ID stored in the #GValue. - * Other #GValue operations (such as converting values between types) are - * provided by this interface. - * - * The code in the example program below demonstrates #GValue's - * features. - * - * |[<!-- language="C" --> - * #include <glib-object.h> - * - * static void - * int2string (const GValue *src_value, - * GValue *dest_value) - * { - * if (g_value_get_int (src_value) == 42) - * g_value_set_static_string (dest_value, "An important number"); - * else - * g_value_set_static_string (dest_value, "What's that?"); - * } - * - * int - * main (int argc, - * char *argv[]) - * { - * // GValues must be initialized - * GValue a = G_VALUE_INIT; - * GValue b = G_VALUE_INIT; - * const gchar *message; - * - * // The GValue starts empty - * g_assert (!G_VALUE_HOLDS_STRING (&a)); - * - * // Put a string in it - * g_value_init (&a, G_TYPE_STRING); - * g_assert (G_VALUE_HOLDS_STRING (&a)); - * g_value_set_static_string (&a, "Hello, world!"); - * g_printf ("%s\n", g_value_get_string (&a)); - * - * // Reset it to its pristine state - * g_value_unset (&a); - * - * // It can then be reused for another type - * g_value_init (&a, G_TYPE_INT); - * g_value_set_int (&a, 42); - * - * // Attempt to transform it into a GValue of type STRING - * g_value_init (&b, G_TYPE_STRING); - * - * // An INT is transformable to a STRING - * g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING)); - * - * g_value_transform (&a, &b); - * g_printf ("%s\n", g_value_get_string (&b)); - * - * // Attempt to transform it again using a custom transform function - * g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string); - * g_value_transform (&a, &b); - * g_printf ("%s\n", g_value_get_string (&b)); - * return 0; - * } - * ]| - * - * See also [gobject-Standard-Parameter-and-Value-Types] for more information on - * validation of #GValue. - * - * For letting a #GValue own (and memory manage) arbitrary types or pointers, - * they need to become a [boxed type][gboxed]. The example below shows how - * the pointer `mystruct` of type `MyStruct` is used as a [boxed type][gboxed]. - * - * |[<!-- language="C" --> - * typedef struct { ... } MyStruct; - * G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free) - * - * // These two lines normally go in a public header. By GObject convention, - * // the naming scheme is NAMESPACE_TYPE_NAME: - * #define MY_TYPE_STRUCT (my_struct_get_type ()) - * GType my_struct_get_type (void); - * - * void - * foo () - * { - * GValue *value = g_new0 (GValue, 1); - * g_value_init (value, MY_TYPE_STRUCT); - * g_value_set_boxed (value, mystruct); - * // [... your code ....] - * g_value_unset (value); - * g_value_free (value); - * } - * ]| - */ - - -/** - * SECTION:gparamspec - * @short_description: Metadata for parameter specifications - * @see_also: g_object_class_install_property(), g_object_set(), - * g_object_get(), g_object_set_property(), g_object_get_property(), - * g_value_register_transform_func() - * @title: GParamSpec - * - * #GParamSpec is an object structure that encapsulates the metadata - * required to specify parameters, such as e.g. #GObject properties. - * - * ## Parameter names # {#canonical-parameter-names} - * - * A property name consists of one or more segments consisting of ASCII letters - * and digits, separated by either the `-` or `_` character. The first - * character of a property name must be a letter. These are the same rules as - * for signal naming (see g_signal_new()). - * - * When creating and looking up a #GParamSpec, either separator can be - * used, but they cannot be mixed. Using `-` is considerably more - * efficient, and is the ‘canonical form’. Using `_` is discouraged. - */ - - -/** - * SECTION:gtype - * @short_description: The GLib Runtime type identification and - * management system - * @title: Type Information - * - * The GType API is the foundation of the GObject system. It provides the - * facilities for registering and managing all fundamental data types, - * user-defined object and interface types. - * - * For type creation and registration purposes, all types fall into one of - * two categories: static or dynamic. Static types are never loaded or - * unloaded at run-time as dynamic types may be. Static types are created - * with g_type_register_static() that gets type specific information passed - * in via a #GTypeInfo structure. - * - * Dynamic types are created with g_type_register_dynamic() which takes a - * #GTypePlugin structure instead. The remaining type information (the - * #GTypeInfo structure) is retrieved during runtime through #GTypePlugin - * and the g_type_plugin_*() API. - * - * These registration functions are usually called only once from a - * function whose only purpose is to return the type identifier for a - * specific class. Once the type (or class or interface) is registered, - * it may be instantiated, inherited, or implemented depending on exactly - * what sort of type it is. - * - * There is also a third registration function for registering fundamental - * types called g_type_register_fundamental() which requires both a #GTypeInfo - * structure and a #GTypeFundamentalInfo structure but it is seldom used - * since most fundamental types are predefined rather than user-defined. - * - * Type instance and class structs are limited to a total of 64 KiB, - * including all parent types. Similarly, type instances' private data - * (as created by G_ADD_PRIVATE()) are limited to a total of - * 64 KiB. If a type instance needs a large static buffer, allocate it - * separately (typically by using #GArray or #GPtrArray) and put a pointer - * to the buffer in the structure. - * - * As mentioned in the [GType conventions][gtype-conventions], type names must - * be at least three characters long. There is no upper length limit. The first - * character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent - * characters can be letters, numbers or any of ‘-_+’. - */ - - -/** - * SECTION:gtypemodule - * @short_description: Type loading modules - * @see_also: #GTypePlugin, #GModule - * @title: GTypeModule - * - * #GTypeModule provides a simple implementation of the #GTypePlugin - * interface. - * - * The model of #GTypeModule is a dynamically loaded module which - * implements some number of types and interface implementations. - * - * When the module is loaded, it registers its types and interfaces - * using g_type_module_register_type() and g_type_module_add_interface(). - * As long as any instances of these types and interface implementations - * are in use, the module is kept loaded. When the types and interfaces - * are gone, the module may be unloaded. If the types and interfaces - * become used again, the module will be reloaded. Note that the last - * reference cannot be released from within the module code, since that - * would lead to the caller's code being unloaded before g_object_unref() - * returns to it. - * - * Keeping track of whether the module should be loaded or not is done by - * using a use count - it starts at zero, and whenever it is greater than - * zero, the module is loaded. The use count is maintained internally by - * the type system, but also can be explicitly controlled by - * g_type_module_use() and g_type_module_unuse(). Typically, when loading - * a module for the first type, g_type_module_use() will be used to load - * it so that it can initialize its types. At some later point, when the - * module no longer needs to be loaded except for the type - * implementations it contains, g_type_module_unuse() is called. - * - * #GTypeModule does not actually provide any implementation of module - * loading and unloading. To create a particular module type you must - * derive from #GTypeModule and implement the load and unload functions - * in #GTypeModuleClass. - */ - - -/** - * SECTION:gtypeplugin - * @short_description: An interface for dynamically loadable types - * @see_also: #GTypeModule and g_type_register_dynamic(). - * @title: GTypePlugin - * - * An interface that handles the lifecycle of dynamically loaded types. - * - * The GObject type system supports dynamic loading of types. - * It goes as follows: - * - * 1. The type is initially introduced (usually upon loading the module - * the first time, or by your main application that knows what modules - * introduces what types), like this: - * |[<!-- language="C" --> - * new_type_id = g_type_register_dynamic (parent_type_id, - * "TypeName", - * new_type_plugin, - * type_flags); - * ]| - * where @new_type_plugin is an implementation of the - * #GTypePlugin interface. - * - * 2. The type's implementation is referenced, e.g. through - * g_type_class_ref() or through g_type_create_instance() (this is - * being called by g_object_new()) or through one of the above done on - * a type derived from @new_type_id. - * - * 3. This causes the type system to load the type's implementation by - * calling g_type_plugin_use() and g_type_plugin_complete_type_info() - * on @new_type_plugin. - * - * 4. At some point the type's implementation isn't required anymore, - * e.g. after g_type_class_unref() or g_type_free_instance() (called - * when the reference count of an instance drops to zero). - * - * 5. This causes the type system to throw away the information retrieved - * from g_type_plugin_complete_type_info() and then it calls - * g_type_plugin_unuse() on @new_type_plugin. - * - * 6. Things may repeat from the second step. - * - * So basically, you need to implement a #GTypePlugin type that - * carries a use_count, once use_count goes from zero to one, you need - * to load the implementation to successfully handle the upcoming - * g_type_plugin_complete_type_info() call. Later, maybe after - * succeeding use/unuse calls, once use_count drops to zero, you can - * unload the implementation again. The type system makes sure to call - * g_type_plugin_use() and g_type_plugin_complete_type_info() again - * when the type is needed again. - * - * #GTypeModule is an implementation of #GTypePlugin that already - * implements most of this except for the actual module loading and - * unloading. It even handles multiple registered types per module. - */ - - -/** - * SECTION:objects - * @title: GObject - * @short_description: The base object type - * @see_also: #GParamSpecObject, g_param_spec_object() - * - * GObject is the fundamental type providing the common attributes and - * methods for all object types in GTK+, Pango and other libraries - * based on GObject. The GObject class provides methods for object - * construction and destruction, property access methods, and signal - * support. Signals are described in detail [here][gobject-Signals]. - * - * For a tutorial on implementing a new GObject class, see [How to define and - * implement a new GObject][howto-gobject]. For a list of naming conventions for - * GObjects and their methods, see the [GType conventions][gtype-conventions]. - * For the high-level concepts behind GObject, read [Instantiatable classed types: - * Objects][gtype-instantiatable-classed]. - * - * ## Floating references # {#floating-ref} - * - * **Note**: Floating references are a C convenience API and should not be - * used in modern GObject code. Language bindings in particular find the - * concept highly problematic, as floating references are not identifiable - * through annotations, and neither are deviations from the floating reference - * behavior, like types that inherit from #GInitiallyUnowned and still return - * a full reference from g_object_new(). - * - * GInitiallyUnowned is derived from GObject. The only difference between - * the two is that the initial reference of a GInitiallyUnowned is flagged - * as a "floating" reference. This means that it is not specifically - * claimed to be "owned" by any code portion. The main motivation for - * providing floating references is C convenience. In particular, it - * allows code to be written as: - * - * |[<!-- language="C" --> - * container = create_container (); - * container_add_child (container, create_child()); - * ]| - * - * If container_add_child() calls g_object_ref_sink() on the passed-in child, - * no reference of the newly created child is leaked. Without floating - * references, container_add_child() can only g_object_ref() the new child, - * so to implement this code without reference leaks, it would have to be - * written as: - * - * |[<!-- language="C" --> - * Child *child; - * container = create_container (); - * child = create_child (); - * container_add_child (container, child); - * g_object_unref (child); - * ]| - * - * The floating reference can be converted into an ordinary reference by - * calling g_object_ref_sink(). For already sunken objects (objects that - * don't have a floating reference anymore), g_object_ref_sink() is equivalent - * to g_object_ref() and returns a new reference. - * - * Since floating references are useful almost exclusively for C convenience, - * language bindings that provide automated reference and memory ownership - * maintenance (such as smart pointers or garbage collection) should not - * expose floating references in their API. The best practice for handling - * types that have initially floating references is to immediately sink those - * references after g_object_new() returns, by checking if the #GType - * inherits from #GInitiallyUnowned. For instance: - * - * |[<!-- language="C" --> - * GObject *res = g_object_new_with_properties (gtype, - * n_props, - * prop_names, - * prop_values); - * - * // or: if (g_type_is_a (gtype, G_TYPE_INITIALLY_UNOWNED)) - * if (G_IS_INITIALLY_UNOWNED (res)) - * g_object_ref_sink (res); - * - * return res; - * ]| - * - * Some object implementations may need to save an objects floating state - * across certain code portions (an example is #GtkMenu), to achieve this, - * the following sequence can be used: - * - * |[<!-- language="C" --> - * // save floating state - * gboolean was_floating = g_object_is_floating (object); - * g_object_ref_sink (object); - * // protected code portion - * - * ... - * - * // restore floating state - * if (was_floating) - * g_object_force_floating (object); - * else - * g_object_unref (object); // release previously acquired reference - * ]| - */ - - -/** - * SECTION:param_value_types - * @short_description: Standard Parameter and Value Types - * @see_also: #GParamSpec, #GValue, g_object_class_install_property(). - * @title: Parameters and Values - * - * #GValue provides an abstract container structure which can be - * copied, transformed and compared while holding a value of any - * (derived) type, which is registered as a #GType with a - * #GTypeValueTable in its #GTypeInfo structure. Parameter - * specifications for most value types can be created as #GParamSpec - * derived instances, to implement e.g. #GObject properties which - * operate on #GValue containers. - * - * Parameter names need to start with a letter (a-z or A-Z). Subsequent - * characters can be letters, numbers or a '-'. - * All other characters are replaced by a '-' during construction. - * - * See also #GValue for more information. - */ - - -/** - * SECTION:signals - * @short_description: A means for customization of object behaviour - * and a general purpose notification mechanism - * @title: Signals - * - * The basic concept of the signal system is that of the emission - * of a signal. Signals are introduced per-type and are identified - * through strings. Signals introduced for a parent type are available - * in derived types as well, so basically they are a per-type facility - * that is inherited. - * - * A signal emission mainly involves invocation of a certain set of - * callbacks in precisely defined manner. There are two main categories - * of such callbacks, per-object ones and user provided ones. - * (Although signals can deal with any kind of instantiatable type, I'm - * referring to those types as "object types" in the following, simply - * because that is the context most users will encounter signals in.) - * The per-object callbacks are most often referred to as "object method - * handler" or "default (signal) handler", while user provided callbacks are - * usually just called "signal handler". - * - * The object method handler is provided at signal creation time (this most - * frequently happens at the end of an object class' creation), while user - * provided handlers are frequently connected and disconnected to/from a - * certain signal on certain object instances. - * - * A signal emission consists of five stages, unless prematurely stopped: - * - * 1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - * - * 2. Invocation of normal user-provided signal handlers (where the @after - * flag is not set) - * - * 3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - * - * 4. Invocation of user provided signal handlers (where the @after flag is set) - * - * 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - * - * The user-provided signal handlers are called in the order they were - * connected in. - * - * All handlers may prematurely stop a signal emission, and any number of - * handlers may be connected, disconnected, blocked or unblocked during - * a signal emission. - * - * There are certain criteria for skipping user handlers in stages 2 and 4 - * of a signal emission. - * - * First, user handlers may be blocked. Blocked handlers are omitted during - * callback invocation, to return from the blocked state, a handler has to - * get unblocked exactly the same amount of times it has been blocked before. - * - * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional - * @detail argument passed in to g_signal_emit() has to match the detail - * argument of the signal handler currently subject to invocation. - * Specification of no detail argument for signal handlers (omission of the - * detail part of the signal specification upon connection) serves as a - * wildcard and matches any detail argument passed in to emission. - * - * While the @detail argument is typically used to pass an object property name - * (as with #GObject::notify), no specific format is mandated for the detail - * string, other than that it must be non-empty. - * - * ## Memory management of signal handlers # {#signal-memory-management} - * - * If you are connecting handlers to signals and using a #GObject instance as - * your signal handler user data, you should remember to pair calls to - * g_signal_connect() with calls to g_signal_handler_disconnect() or - * g_signal_handlers_disconnect_by_func(). While signal handlers are - * automatically disconnected when the object emitting the signal is finalised, - * they are not automatically disconnected when the signal handler user data is - * destroyed. If this user data is a #GObject instance, using it from a - * signal handler after it has been finalised is an error. - * - * There are two strategies for managing such user data. The first is to - * disconnect the signal handler (using g_signal_handler_disconnect() or - * g_signal_handlers_disconnect_by_func()) when the user data (object) is - * finalised; this has to be implemented manually. For non-threaded programs, - * g_signal_connect_object() can be used to implement this automatically. - * Currently, however, it is unsafe to use in threaded programs. - * - * The second is to hold a strong reference on the user data until after the - * signal is disconnected for other reasons. This can be implemented - * automatically using g_signal_connect_data(). - * - * The first approach is recommended, as the second approach can result in - * effective memory leaks of the user data if the signal handler is never - * disconnected for some reason. - */ - - -/** - * SECTION:value_arrays - * @short_description: A container structure to maintain an array of - * generic values - * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array() - * @title: Value arrays - * - * The prime purpose of a #GValueArray is for it to be used as an - * object property that holds an array of values. A #GValueArray wraps - * an array of #GValue elements in order for it to be used as a boxed - * type through %G_TYPE_VALUE_ARRAY. - * - * #GValueArray is deprecated in favour of #GArray since GLib 2.32. It - * is possible to create a #GArray that behaves like a #GValueArray by - * using the size of #GValue as the element size, and by setting - * g_value_unset() as the clear function using g_array_set_clear_func(), - * for instance, the following code: - * - * |[<!-- language="C" --> - * GValueArray *array = g_value_array_new (10); - * ]| - * - * can be replaced by: - * - * |[<!-- language="C" --> - * GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); - * g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); - * ]| - * - * Deprecated: 2.32: Use #GArray instead, if possible for the given use case, - * as described above. - */ - - -/** - * g_binding_dup_source: - * @binding: a #GBinding - * - * Retrieves the #GObject instance used as the source of the binding. - * - * A #GBinding can outlive the source #GObject as the binding does not hold a - * strong reference to the source. If the source is destroyed before the - * binding then this function will return %NULL. - * - * Returns: (transfer full) (nullable): the source #GObject, or %NULL if the - * source does not exist any more. - * Since: 2.68 - */ - - -/** - * g_binding_dup_target: - * @binding: a #GBinding - * - * Retrieves the #GObject instance used as the target of the binding. - * - * A #GBinding can outlive the target #GObject as the binding does not hold a - * strong reference to the target. If the target is destroyed before the - * binding then this function will return %NULL. - * - * Returns: (transfer full) (nullable): the target #GObject, or %NULL if the - * target does not exist any more. - * Since: 2.68 - */ - - -/** - * g_binding_get_flags: - * @binding: a #GBinding - * - * Retrieves the flags passed when constructing the #GBinding. - * - * Returns: the #GBindingFlags used by the #GBinding - * Since: 2.26 - */ - - -/** - * g_binding_get_source: - * @binding: a #GBinding - * - * Retrieves the #GObject instance used as the source of the binding. - * - * A #GBinding can outlive the source #GObject as the binding does not hold a - * strong reference to the source. If the source is destroyed before the - * binding then this function will return %NULL. - * - * Use g_binding_dup_source() if the source or binding are used from different - * threads as otherwise the pointer returned from this function might become - * invalid if the source is finalized from another thread in the meantime. - * - * Returns: (transfer none) (nullable): the source #GObject, or %NULL if the - * source does not exist any more. - * Deprecated: 2.68: Use g_binding_dup_source() for a safer version of this - * function. - * Since: 2.26 - */ - - -/** - * g_binding_get_source_property: - * @binding: a #GBinding - * - * Retrieves the name of the property of #GBinding:source used as the source - * of the binding. - * - * Returns: the name of the source property - * Since: 2.26 - */ - - -/** - * g_binding_get_target: - * @binding: a #GBinding - * - * Retrieves the #GObject instance used as the target of the binding. - * - * A #GBinding can outlive the target #GObject as the binding does not hold a - * strong reference to the target. If the target is destroyed before the - * binding then this function will return %NULL. - * - * Use g_binding_dup_target() if the target or binding are used from different - * threads as otherwise the pointer returned from this function might become - * invalid if the target is finalized from another thread in the meantime. - * - * Returns: (transfer none) (nullable): the target #GObject, or %NULL if the - * target does not exist any more. - * Deprecated: 2.68: Use g_binding_dup_target() for a safer version of this - * function. - * Since: 2.26 - */ - - -/** - * g_binding_get_target_property: - * @binding: a #GBinding - * - * Retrieves the name of the property of #GBinding:target used as the target - * of the binding. - * - * Returns: the name of the target property - * Since: 2.26 - */ - - -/** - * g_binding_unbind: - * @binding: a #GBinding - * - * Explicitly releases the binding between the source and the target - * property expressed by @binding. - * - * This function will release the reference that is being held on - * the @binding instance if the binding is still bound; if you want to hold on - * to the #GBinding instance after calling g_binding_unbind(), you will need - * to hold a reference to it. - * - * Note however that this function does not take ownership of @binding, it - * only unrefs the reference that was initially created by - * g_object_bind_property() and is owned by the binding. - * - * Since: 2.38 - */ - - -/** - * g_boxed_copy: - * @boxed_type: The type of @src_boxed. - * @src_boxed: (not nullable): The boxed structure to be copied. - * - * Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. - * - * Returns: (transfer full) (not nullable): The newly created copy of the boxed - * structure. - */ - - -/** - * g_boxed_free: - * @boxed_type: The type of @boxed. - * @boxed: (not nullable): The boxed structure to be freed. - * - * Free the boxed structure @boxed which is of type @boxed_type. - */ - - -/** - * g_boxed_type_register_static: - * @name: Name of the new boxed type. - * @boxed_copy: Boxed structure copy function. - * @boxed_free: Boxed structure free function. - * - * This function creates a new %G_TYPE_BOXED derived type id for a new - * boxed type with name @name. - * - * Boxed type handling functions have to be provided to copy and free - * opaque boxed structures of this type. - * - * For the general case, it is recommended to use #G_DEFINE_BOXED_TYPE - * instead of calling g_boxed_type_register_static() directly. The macro - * will create the appropriate `*_get_type()` function for the boxed type. - * - * Returns: New %G_TYPE_BOXED derived type id for @name. - */ - - -/** - * g_cclosure_marshal_BOOLEAN__BOXED_BOXED: - * @closure: A #GClosure. - * @return_value: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * - * A #GClosureMarshal function for use with signals with handlers that - * take two boxed pointers as arguments and return a boolean. If you - * have such a signal, you will probably also need to use an - * accumulator, such as g_signal_accumulator_true_handled(). - */ - - -/** - * g_cclosure_marshal_BOOLEAN__BOXED_BOXEDv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__BOXED_BOXED(). - */ - - -/** - * g_cclosure_marshal_BOOLEAN__FLAGS: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue which can store the returned #gboolean - * @n_param_values: 2 - * @param_values: a #GValue array holding instance and arg1 - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter - * denotes a flags type. - */ - - -/** - * g_cclosure_marshal_BOOLEAN__FLAGSv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__FLAGS(). - */ - - -/** - * g_cclosure_marshal_BOOLEAN__OBJECT_BOXED_BOXED: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue, which can store the returned string - * @n_param_values: 3 - * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)`. - * - * Since: 2.26 - */ - - -/** - * g_cclosure_marshal_BOOL__FLAGS: - * - * Another name for g_cclosure_marshal_BOOLEAN__FLAGS(). - */ - - -/** - * g_cclosure_marshal_STRING__OBJECT_POINTER: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue, which can store the returned string - * @n_param_values: 3 - * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_STRING__OBJECT_POINTERv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_STRING__OBJECT_POINTER(). - */ - - -/** - * g_cclosure_marshal_VOID__BOOLEAN: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gboolean parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__BOOLEANv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOOLEAN(). - */ - - -/** - * g_cclosure_marshal_VOID__BOXED: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GBoxed* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__BOXEDv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOXED(). - */ - - -/** - * g_cclosure_marshal_VOID__CHAR: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gchar parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__CHARv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__CHAR(). - */ - - -/** - * g_cclosure_marshal_VOID__DOUBLE: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gdouble parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__DOUBLEv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__DOUBLE(). - */ - - -/** - * g_cclosure_marshal_VOID__ENUM: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the enumeration parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. - */ - - -/** - * g_cclosure_marshal_VOID__ENUMv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ENUM(). - */ - - -/** - * g_cclosure_marshal_VOID__FLAGS: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the flags parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. - */ - - -/** - * g_cclosure_marshal_VOID__FLAGSv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLAGS(). - */ - - -/** - * g_cclosure_marshal_VOID__FLOAT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gfloat parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__FLOATv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLOAT(). - */ - - -/** - * g_cclosure_marshal_VOID__INT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gint parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__INTv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__INT(). - */ - - -/** - * g_cclosure_marshal_VOID__LONG: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #glong parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__LONGv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__LONG(). - */ - - -/** - * g_cclosure_marshal_VOID__OBJECT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GObject* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__OBJECTv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__OBJECT(). - */ - - -/** - * g_cclosure_marshal_VOID__PARAM: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GParamSpec* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__PARAMv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__PARAM(). - */ - - -/** - * g_cclosure_marshal_VOID__POINTER: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gpointer parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__POINTERv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__POINTER(). - */ - - -/** - * g_cclosure_marshal_VOID__STRING: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gchar* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__STRINGv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__STRING(). - */ - - -/** - * g_cclosure_marshal_VOID__UCHAR: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #guchar parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__UCHARv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UCHAR(). - */ - - -/** - * g_cclosure_marshal_VOID__UINT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #guint parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__UINT_POINTER: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 3 - * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__UINT_POINTERv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT_POINTER(). - */ - - -/** - * g_cclosure_marshal_VOID__UINTv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT(). - */ - - -/** - * g_cclosure_marshal_VOID__ULONG: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gulong parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__ULONGv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ULONG(). - */ - - -/** - * g_cclosure_marshal_VOID__VARIANT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GVariant* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. - * - * Since: 2.26 - */ - - -/** - * g_cclosure_marshal_VOID__VARIANTv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VARIANT(). - */ - - -/** - * g_cclosure_marshal_VOID__VOID: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 1 - * @param_values: a #GValue array holding only the instance - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller - * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gpointer user_data)`. - */ - - -/** - * g_cclosure_marshal_VOID__VOIDv: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is invoked. - * @args: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args. - * - * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VOID(). - */ - - -/** - * g_cclosure_marshal_generic: - * @closure: A #GClosure. - * @return_gvalue: A #GValue to store the return value. May be %NULL - * if the callback of closure doesn't return a value. - * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValues holding the arguments - * on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to - * g_closure_invoke(). - * @marshal_data: Additional data specified when registering the - * marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * - * A generic marshaller function implemented via - * [libffi](http://sourceware.org/libffi/). - * - * Normally this function is not passed explicitly to g_signal_new(), - * but used automatically by GLib when specifying a %NULL marshaller. - * - * Since: 2.30 - */ - - -/** - * g_cclosure_marshal_generic_va: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: (nullable): a #GValue to store the return - * value. May be %NULL if the callback of @closure doesn't return a - * value. - * @instance: (type GObject.TypeInstance): the instance on which the closure is - * invoked. - * @args_list: va_list of arguments to be passed to the closure. - * @marshal_data: (nullable): additional data specified when - * registering the marshaller, see g_closure_set_marshal() and - * g_closure_set_meta_marshal() - * @n_params: the length of the @param_types array - * @param_types: (array length=n_params): the #GType of each argument from - * @args_list. - * - * A generic #GVaClosureMarshal function implemented via - * [libffi](http://sourceware.org/libffi/). - * - * Since: 2.30 - */ - - -/** - * g_cclosure_new: (skip) - * @callback_func: the function to invoke - * @user_data: (closure callback_func): user data to pass to @callback_func - * @destroy_data: destroy notify to be called when @user_data is no longer used - * - * Creates a new closure which invokes @callback_func with @user_data as - * the last parameter. - * - * @destroy_data will be called as a finalize notifier on the #GClosure. - * - * Returns: (transfer none): a floating reference to a new #GCClosure - */ - - -/** - * g_cclosure_new_object: (skip) - * @callback_func: the function to invoke - * @object: a #GObject pointer to pass to @callback_func - * - * A variant of g_cclosure_new() which uses @object as @user_data and - * calls g_object_watch_closure() on @object and the created - * closure. This function is useful when you have a callback closely - * associated with a #GObject, and want the callback to no longer run - * after the object is is freed. - * - * Returns: (transfer floating): a new #GCClosure - */ - - -/** - * g_cclosure_new_object_swap: (skip) - * @callback_func: the function to invoke - * @object: a #GObject pointer to pass to @callback_func - * - * A variant of g_cclosure_new_swap() which uses @object as @user_data - * and calls g_object_watch_closure() on @object and the created - * closure. This function is useful when you have a callback closely - * associated with a #GObject, and want the callback to no longer run - * after the object is is freed. - * - * Returns: (transfer floating): a new #GCClosure - */ - - -/** - * g_cclosure_new_swap: (skip) - * @callback_func: the function to invoke - * @user_data: (closure callback_func): user data to pass to @callback_func - * @destroy_data: destroy notify to be called when @user_data is no longer used - * - * Creates a new closure which invokes @callback_func with @user_data as - * the first parameter. - * - * @destroy_data will be called as a finalize notifier on the #GClosure. - * - * Returns: (transfer none): a floating reference to a new #GCClosure - */ - - -/** - * g_clear_object: (skip) - * @object_ptr: a pointer to a #GObject reference - * - * Clears a reference to a #GObject. - * - * @object_ptr must not be %NULL. - * - * If the reference is %NULL then this function does nothing. - * Otherwise, the reference count of the object is decreased and the - * pointer is set to %NULL. - * - * A macro is also included that allows this function to be used without - * pointer casts. - * - * Since: 2.28 - */ - - -/** - * g_clear_signal_handler: - * @handler_id_ptr: A pointer to a handler ID (of type #gulong) of the handler to be disconnected. - * @instance: (type GObject.Object): The instance to remove the signal handler from. - * This pointer may be %NULL or invalid, if the handler ID is zero. - * - * Disconnects a handler from @instance so it will not be called during - * any future or currently ongoing emissions of the signal it has been - * connected to. The @handler_id_ptr is then set to zero, which is never a valid handler ID value (see g_signal_connect()). - * - * If the handler ID is 0 then this function does nothing. - * - * There is also a macro version of this function so that the code - * will be inlined. - * - * Since: 2.62 - */ - - -/** - * g_closure_add_finalize_notifier: (skip) - * @closure: a #GClosure - * @notify_data: (closure notify_func): data to pass to @notify_func - * @notify_func: the callback function to register - * - * Registers a finalization notifier which will be called when the - * reference count of @closure goes down to 0. - * - * Multiple finalization notifiers on a single closure are invoked in - * unspecified order. If a single call to g_closure_unref() results in - * the closure being both invalidated and finalized, then the invalidate - * notifiers will be run before the finalize notifiers. - */ - - -/** - * g_closure_add_invalidate_notifier: (skip) - * @closure: a #GClosure - * @notify_data: (closure notify_func): data to pass to @notify_func - * @notify_func: the callback function to register - * - * Registers an invalidation notifier which will be called when the - * @closure is invalidated with g_closure_invalidate(). - * - * Invalidation notifiers are invoked before finalization notifiers, - * in an unspecified order. - */ - - -/** - * g_closure_add_marshal_guards: (skip) - * @closure: a #GClosure - * @pre_marshal_data: (closure pre_marshal_notify): data to pass - * to @pre_marshal_notify - * @pre_marshal_notify: a function to call before the closure callback - * @post_marshal_data: (closure post_marshal_notify): data to pass - * to @post_marshal_notify - * @post_marshal_notify: a function to call after the closure callback - * - * Adds a pair of notifiers which get invoked before and after the - * closure callback, respectively. - * - * This is typically used to protect the extra arguments for the - * duration of the callback. See g_object_watch_closure() for an - * example of marshal guards. - */ - - -/** - * g_closure_invalidate: - * @closure: #GClosure to invalidate - * - * Sets a flag on the closure to indicate that its calling - * environment has become invalid, and thus causes any future - * invocations of g_closure_invoke() on this @closure to be - * ignored. - * - * Also, invalidation notifiers installed on the closure will - * be called at this point. Note that unless you are holding a - * reference to the closure yourself, the invalidation notifiers may - * unref the closure and cause it to be destroyed, so if you need to - * access the closure after calling g_closure_invalidate(), make sure - * that you've previously called g_closure_ref(). - * - * Note that g_closure_invalidate() will also be called when the - * reference count of a closure drops to zero (unless it has already - * been invalidated before). - */ - - -/** - * g_closure_invoke: - * @closure: a #GClosure - * @return_value: (optional) (out): a #GValue to store the return - * value. May be %NULL if the callback of @closure - * doesn't return a value. - * @n_param_values: the length of the @param_values array - * @param_values: (array length=n_param_values): an array of - * #GValues holding the arguments on which to - * invoke the callback of @closure - * @invocation_hint: (nullable): a context-dependent invocation hint - * - * Invokes the closure, i.e. executes the callback represented by the @closure. - */ - - -/** - * g_closure_new_object: - * @sizeof_closure: the size of the structure to allocate, must be at least - * `sizeof (GClosure)` - * @object: a #GObject pointer to store in the @data field of the newly - * allocated #GClosure - * - * A variant of g_closure_new_simple() which stores @object in the - * @data field of the closure and calls g_object_watch_closure() on - * @object and the created closure. This function is mainly useful - * when implementing new types of closures. - * - * Returns: (transfer floating): a newly allocated #GClosure - */ - - -/** - * g_closure_new_simple: - * @sizeof_closure: the size of the structure to allocate, must be at least - * `sizeof (GClosure)` - * @data: data to store in the @data field of the newly allocated #GClosure - * - * Allocates a struct of the given size and initializes the initial - * part as a #GClosure. - * - * This function is mainly useful when implementing new types of closures: - * - * |[<!-- language="C" --> - * typedef struct _MyClosure MyClosure; - * struct _MyClosure - * { - * GClosure closure; - * // extra data goes here - * }; - * - * static void - * my_closure_finalize (gpointer notify_data, - * GClosure *closure) - * { - * MyClosure *my_closure = (MyClosure *)closure; - * - * // free extra data here - * } - * - * MyClosure *my_closure_new (gpointer data) - * { - * GClosure *closure; - * MyClosure *my_closure; - * - * closure = g_closure_new_simple (sizeof (MyClosure), data); - * my_closure = (MyClosure *) closure; - * - * // initialize extra data here - * - * g_closure_add_finalize_notifier (closure, notify_data, - * my_closure_finalize); - * return my_closure; - * } - * ]| - * - * Returns: (transfer none): a floating reference to a new #GClosure - */ - - -/** - * g_closure_ref: - * @closure: #GClosure to increment the reference count on - * - * Increments the reference count on a closure to force it staying - * alive while the caller holds a pointer to it. - * - * Returns: (transfer none): The @closure passed in, for convenience - */ - - -/** - * g_closure_remove_finalize_notifier: (skip) - * @closure: a #GClosure - * @notify_data: data which was passed to g_closure_add_finalize_notifier() - * when registering @notify_func - * @notify_func: the callback function to remove - * - * Removes a finalization notifier. - * - * Notice that notifiers are automatically removed after they are run. - */ - - -/** - * g_closure_remove_invalidate_notifier: (skip) - * @closure: a #GClosure - * @notify_data: data which was passed to g_closure_add_invalidate_notifier() - * when registering @notify_func - * @notify_func: the callback function to remove - * - * Removes an invalidation notifier. - * - * Notice that notifiers are automatically removed after they are run. - */ - - -/** - * g_closure_set_marshal: (skip) - * @closure: a #GClosure - * @marshal: a #GClosureMarshal function - * - * Sets the marshaller of @closure. - * - * The `marshal_data` of @marshal provides a way for a meta marshaller to - * provide additional information to the marshaller. - * - * For GObject's C predefined marshallers (the `g_cclosure_marshal_*()` - * functions), what it provides is a callback function to use instead of - * @closure->callback. - * - * See also: g_closure_set_meta_marshal() - */ - - -/** - * g_closure_set_meta_marshal: (skip) - * @closure: a #GClosure - * @marshal_data: (closure meta_marshal): context-dependent data to pass - * to @meta_marshal - * @meta_marshal: a #GClosureMarshal function - * - * Sets the meta marshaller of @closure. - * - * A meta marshaller wraps the @closure's marshal and modifies the way - * it is called in some fashion. The most common use of this facility - * is for C callbacks. - * - * The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), - * are used everywhere, but the way that we get the callback function - * differs. In most cases we want to use the @closure's callback, but in - * other cases we want to use some different technique to retrieve the - * callback function. - * - * For example, class closures for signals (see - * g_signal_type_cclosure_new()) retrieve the callback function from a - * fixed offset in the class structure. The meta marshaller retrieves - * the right callback and passes it to the marshaller as the - * @marshal_data argument. - */ - - -/** - * g_closure_sink: - * @closure: #GClosure to decrement the initial reference count on, if it's - * still being held - * - * Takes over the initial ownership of a closure. - * - * Each closure is initially created in a "floating" state, which means - * that the initial reference count is not owned by any caller. - * - * This function checks to see if the object is still floating, and if so, - * unsets the floating state and decreases the reference count. If the - * closure is not floating, g_closure_sink() does nothing. - * - * The reason for the existence of the floating state is to prevent - * cumbersome code sequences like: - * - * |[<!-- language="C" --> - * closure = g_cclosure_new (cb_func, cb_data); - * g_source_set_closure (source, closure); - * g_closure_unref (closure); // GObject doesn't really need this - * ]| - * - * Because g_source_set_closure() (and similar functions) take ownership of the - * initial reference count, if it is unowned, we instead can write: - * - * |[<!-- language="C" --> - * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); - * ]| - * - * Generally, this function is used together with g_closure_ref(). An example - * of storing a closure for later notification looks like: - * - * |[<!-- language="C" --> - * static GClosure *notify_closure = NULL; - * void - * foo_notify_set_closure (GClosure *closure) - * { - * if (notify_closure) - * g_closure_unref (notify_closure); - * notify_closure = closure; - * if (notify_closure) - * { - * g_closure_ref (notify_closure); - * g_closure_sink (notify_closure); - * } - * } - * ]| - * - * Because g_closure_sink() may decrement the reference count of a closure - * (if it hasn't been called on @closure yet) just like g_closure_unref(), - * g_closure_ref() should be called prior to this function. - */ - - -/** - * g_closure_unref: - * @closure: #GClosure to decrement the reference count on - * - * Decrements the reference count of a closure after it was previously - * incremented by the same caller. - * - * If no other callers are using the closure, then the closure will be - * destroyed and freed. - */ - - -/** - * g_enum_complete_type_info: - * @g_enum_type: the type identifier of the type being completed - * @info: (out callee-allocates): the #GTypeInfo struct to be filled in - * @const_values: An array of #GEnumValue structs for the possible - * enumeration values. The array is terminated by a struct with all - * members being 0. - * - * This function is meant to be called from the `complete_type_info` - * function of a #GTypePlugin implementation, as in the following - * example: - * - * |[<!-- language="C" --> - * static void - * my_enum_complete_type_info (GTypePlugin *plugin, - * GType g_type, - * GTypeInfo *info, - * GTypeValueTable *value_table) - * { - * static const GEnumValue values[] = { - * { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" }, - * { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }, - * { 0, NULL, NULL } - * }; - * - * g_enum_complete_type_info (type, info, values); - * } - * ]| - */ - - -/** - * g_enum_get_value: - * @enum_class: a #GEnumClass - * @value: the value to look up - * - * Returns the #GEnumValue for a value. - * - * Returns: (transfer none) (nullable): the #GEnumValue for @value, or %NULL - * if @value is not a member of the enumeration - */ - - -/** - * g_enum_get_value_by_name: - * @enum_class: a #GEnumClass - * @name: the name to look up - * - * Looks up a #GEnumValue by name. - * - * Returns: (transfer none) (nullable): the #GEnumValue with name @name, - * or %NULL if the enumeration doesn't have a member - * with that name - */ - - -/** - * g_enum_get_value_by_nick: - * @enum_class: a #GEnumClass - * @nick: the nickname to look up - * - * Looks up a #GEnumValue by nickname. - * - * Returns: (transfer none) (nullable): the #GEnumValue with nickname @nick, - * or %NULL if the enumeration doesn't have a member - * with that nickname - */ - - -/** - * g_enum_register_static: - * @name: A nul-terminated string used as the name of the new type. - * @const_static_values: An array of #GEnumValue structs for the possible - * enumeration values. The array is terminated by a struct with all - * members being 0. GObject keeps a reference to the data, so it cannot - * be stack-allocated. - * - * Registers a new static enumeration type with the name @name. - * - * It is normally more convenient to let [glib-mkenums][glib-mkenums], - * generate a my_enum_get_type() function from a usual C enumeration - * definition than to write one yourself using g_enum_register_static(). - * - * Returns: The new type identifier. - */ - - -/** - * g_enum_to_string: - * @g_enum_type: the type identifier of a #GEnumClass type - * @value: the value - * - * Pretty-prints @value in the form of the enum’s name. - * - * This is intended to be used for debugging purposes. The format of the output - * may change in the future. - * - * Returns: (transfer full): a newly-allocated text string - * Since: 2.54 - */ - - -/** - * g_flags_complete_type_info: - * @g_flags_type: the type identifier of the type being completed - * @info: (out callee-allocates): the #GTypeInfo struct to be filled in - * @const_values: An array of #GFlagsValue structs for the possible - * enumeration values. The array is terminated by a struct with all - * members being 0. - * - * This function is meant to be called from the complete_type_info() - * function of a #GTypePlugin implementation, see the example for - * g_enum_complete_type_info() above. - */ - - -/** - * g_flags_get_first_value: - * @flags_class: a #GFlagsClass - * @value: the value - * - * Returns the first #GFlagsValue which is set in @value. - * - * Returns: (transfer none) (nullable): the first #GFlagsValue which is set in - * @value, or %NULL if none is set - */ - - -/** - * g_flags_get_value_by_name: - * @flags_class: a #GFlagsClass - * @name: the name to look up - * - * Looks up a #GFlagsValue by name. - * - * Returns: (transfer none) (nullable): the #GFlagsValue with name @name, - * or %NULL if there is no flag with that name - */ - - -/** - * g_flags_get_value_by_nick: - * @flags_class: a #GFlagsClass - * @nick: the nickname to look up - * - * Looks up a #GFlagsValue by nickname. - * - * Returns: (transfer none) (nullable): the #GFlagsValue with nickname @nick, - * or %NULL if there is no flag with that nickname - */ - - -/** - * g_flags_register_static: - * @name: A nul-terminated string used as the name of the new type. - * @const_static_values: An array of #GFlagsValue structs for the possible - * flags values. The array is terminated by a struct with all members being 0. - * GObject keeps a reference to the data, so it cannot be stack-allocated. - * - * Registers a new static flags type with the name @name. - * - * It is normally more convenient to let [glib-mkenums][glib-mkenums] - * generate a my_flags_get_type() function from a usual C enumeration - * definition than to write one yourself using g_flags_register_static(). - * - * Returns: The new type identifier. - */ - - -/** - * g_flags_to_string: - * @flags_type: the type identifier of a #GFlagsClass type - * @value: the value - * - * Pretty-prints @value in the form of the flag names separated by ` | ` and - * sorted. Any extra bits will be shown at the end as a hexadecimal number. - * - * This is intended to be used for debugging purposes. The format of the output - * may change in the future. - * - * Returns: (transfer full): a newly-allocated text string - * Since: 2.54 - */ - - -/** - * g_object_add_toggle_ref: (skip) - * @object: a #GObject - * @notify: a function to call when this reference is the - * last reference to the object, or is no longer - * the last reference. - * @data: data to pass to @notify - * - * Increases the reference count of the object by one and sets a - * callback to be called when all other references to the object are - * dropped, or when this is already the last reference to the object - * and another reference is established. - * - * This functionality is intended for binding @object to a proxy - * object managed by another memory manager. This is done with two - * paired references: the strong reference added by - * g_object_add_toggle_ref() and a reverse reference to the proxy - * object which is either a strong reference or weak reference. - * - * The setup is that when there are no other references to @object, - * only a weak reference is held in the reverse direction from @object - * to the proxy object, but when there are other references held to - * @object, a strong reference is held. The @notify callback is called - * when the reference from @object to the proxy object should be - * "toggled" from strong to weak (@is_last_ref true) or weak to strong - * (@is_last_ref false). - * - * Since a (normal) reference must be held to the object before - * calling g_object_add_toggle_ref(), the initial state of the reverse - * link is always strong. - * - * Multiple toggle references may be added to the same gobject, - * however if there are multiple toggle references to an object, none - * of them will ever be notified until all but one are removed. For - * this reason, you should only ever use a toggle reference if there - * is important state in the proxy object. - * - * Since: 2.8 - */ - - -/** - * g_object_add_weak_pointer: (skip) - * @object: The object that should be weak referenced. - * @weak_pointer_location: (inout) (not optional): The memory address - * of a pointer. - * - * Adds a weak reference from weak_pointer to @object to indicate that - * the pointer located at @weak_pointer_location is only valid during - * the lifetime of @object. When the @object is finalized, - * @weak_pointer will be set to %NULL. - * - * Note that as with g_object_weak_ref(), the weak references created by - * this method are not thread-safe: they cannot safely be used in one - * thread if the object's last g_object_unref() might happen in another - * thread. Use #GWeakRef if thread-safety is required. - */ - - -/** - * g_object_bind_property: - * @source: (type GObject.Object): the source #GObject - * @source_property: the property on @source to bind - * @target: (type GObject.Object): the target #GObject - * @target_property: the property on @target to bind - * @flags: flags to pass to #GBinding - * - * Creates a binding between @source_property on @source and @target_property - * on @target. - * - * Whenever the @source_property is changed the @target_property is - * updated using the same value. For instance: - * - * |[<!-- language="C" --> - * g_object_bind_property (action, "active", widget, "sensitive", 0); - * ]| - * - * Will result in the "sensitive" property of the widget #GObject instance to be - * updated with the same value of the "active" property of the action #GObject - * instance. - * - * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: - * if @target_property on @target changes then the @source_property on @source - * will be updated as well. - * - * The binding will automatically be removed when either the @source or the - * @target instances are finalized. To remove the binding without affecting the - * @source and the @target you can just call g_object_unref() on the returned - * #GBinding instance. - * - * Removing the binding by calling g_object_unref() on it must only be done if - * the binding, @source and @target are only used from a single thread and it - * is clear that both @source and @target outlive the binding. Especially it - * is not safe to rely on this if the binding, @source or @target can be - * finalized from different threads. Keep another reference to the binding and - * use g_binding_unbind() instead to be on the safe side. - * - * A #GObject can have multiple bindings. - * - * Returns: (transfer none): the #GBinding instance representing the - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. - * Since: 2.26 - */ - - -/** - * g_object_bind_property_full: - * @source: (type GObject.Object): the source #GObject - * @source_property: the property on @source to bind - * @target: (type GObject.Object): the target #GObject - * @target_property: the property on @target to bind - * @flags: flags to pass to #GBinding - * @transform_to: (scope notified) (nullable): the transformation function - * from the @source to the @target, or %NULL to use the default - * @transform_from: (scope notified) (nullable): the transformation function - * from the @target to the @source, or %NULL to use the default - * @user_data: custom data to be passed to the transformation functions, - * or %NULL - * @notify: (nullable): a function to call when disposing the binding, to free - * resources used by the transformation functions, or %NULL if not required - * - * Complete version of g_object_bind_property(). - * - * Creates a binding between @source_property on @source and @target_property - * on @target, allowing you to set the transformation functions to be used by - * the binding. - * - * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: - * if @target_property on @target changes then the @source_property on @source - * will be updated as well. The @transform_from function is only used in case - * of bidirectional bindings, otherwise it will be ignored - * - * The binding will automatically be removed when either the @source or the - * @target instances are finalized. This will release the reference that is - * being held on the #GBinding instance; if you want to hold on to the - * #GBinding instance, you will need to hold a reference to it. - * - * To remove the binding, call g_binding_unbind(). - * - * A #GObject can have multiple bindings. - * - * The same @user_data parameter will be used for both @transform_to - * and @transform_from transformation functions; the @notify function will - * be called once, when the binding is removed. If you need different data - * for each transformation function, please use - * g_object_bind_property_with_closures() instead. - * - * Returns: (transfer none): the #GBinding instance representing the - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. - * Since: 2.26 - */ - - -/** - * g_object_bind_property_with_closures: (rename-to g_object_bind_property_full) - * @source: (type GObject.Object): the source #GObject - * @source_property: the property on @source to bind - * @target: (type GObject.Object): the target #GObject - * @target_property: the property on @target to bind - * @flags: flags to pass to #GBinding - * @transform_to: a #GClosure wrapping the transformation function - * from the @source to the @target, or %NULL to use the default - * @transform_from: a #GClosure wrapping the transformation function - * from the @target to the @source, or %NULL to use the default - * - * Creates a binding between @source_property on @source and @target_property - * on @target, allowing you to set the transformation functions to be used by - * the binding. - * - * This function is the language bindings friendly version of - * g_object_bind_property_full(), using #GClosures instead of - * function pointers. - * - * Returns: (transfer none): the #GBinding instance representing the - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. - * Since: 2.26 - */ - - -/** - * g_object_class_find_property: - * @oclass: a #GObjectClass - * @property_name: the name of the property to look up - * - * Looks up the #GParamSpec for a property of a class. - * - * Returns: (transfer none): the #GParamSpec for the property, or - * %NULL if the class doesn't have a property of that name - */ - - -/** - * g_object_class_install_properties: - * @oclass: a #GObjectClass - * @n_pspecs: the length of the #GParamSpecs array - * @pspecs: (array length=n_pspecs): the #GParamSpecs array - * defining the new properties - * - * Installs new properties from an array of #GParamSpecs. - * - * All properties should be installed during the class initializer. It - * is possible to install properties after that, but doing so is not - * recommend, and specifically, is not guaranteed to be thread-safe vs. - * use of properties on the same type on other threads. - * - * The property id of each property is the index of each #GParamSpec in - * the @pspecs array. - * - * The property id of 0 is treated specially by #GObject and it should not - * be used to store a #GParamSpec. - * - * This function should be used if you plan to use a static array of - * #GParamSpecs and g_object_notify_by_pspec(). For instance, this - * class initialization: - * - * |[<!-- language="C" --> - * enum { - * PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES - * }; - * - * static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, }; - * - * static void - * my_object_class_init (MyObjectClass *klass) - * { - * GObjectClass *gobject_class = G_OBJECT_CLASS (klass); - * - * obj_properties[PROP_FOO] = - * g_param_spec_int ("foo", "Foo", "Foo", - * -1, G_MAXINT, - * 0, - * G_PARAM_READWRITE); - * - * obj_properties[PROP_BAR] = - * g_param_spec_string ("bar", "Bar", "Bar", - * NULL, - * G_PARAM_READWRITE); - * - * gobject_class->set_property = my_object_set_property; - * gobject_class->get_property = my_object_get_property; - * g_object_class_install_properties (gobject_class, - * N_PROPERTIES, - * obj_properties); - * } - * ]| - * - * allows calling g_object_notify_by_pspec() to notify of property changes: - * - * |[<!-- language="C" --> - * void - * my_object_set_foo (MyObject *self, gint foo) - * { - * if (self->foo != foo) - * { - * self->foo = foo; - * g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]); - * } - * } - * ]| - * - * Since: 2.26 - */ - - -/** - * g_object_class_install_property: - * @oclass: a #GObjectClass - * @property_id: the id for the new property - * @pspec: the #GParamSpec for the new property - * - * Installs a new property. - * - * All properties should be installed during the class initializer. It - * is possible to install properties after that, but doing so is not - * recommend, and specifically, is not guaranteed to be thread-safe vs. - * use of properties on the same type on other threads. - * - * Note that it is possible to redefine a property in a derived class, - * by installing a property with the same name. This can be useful at times, - * e.g. to change the range of allowed values or the default value. - */ - - -/** - * g_object_class_list_properties: - * @oclass: a #GObjectClass - * @n_properties: (out): return location for the length of the returned array - * - * Get an array of #GParamSpec* for all properties of a class. - * - * Returns: (array length=n_properties) (transfer container): an array of - * #GParamSpec* which should be freed after use - */ - - -/** - * g_object_class_override_property: - * @oclass: a #GObjectClass - * @property_id: the new property ID - * @name: the name of a property registered in a parent class or - * in an interface of this class. - * - * Registers @property_id as referring to a property with the name - * @name in a parent class or in an interface implemented by @oclass. - * This allows this class to "override" a property implementation in - * a parent class or to provide the implementation of a property from - * an interface. - * - * Internally, overriding is implemented by creating a property of type - * #GParamSpecOverride; generally operations that query the properties of - * the object class, such as g_object_class_find_property() or - * g_object_class_list_properties() will return the overridden - * property. However, in one case, the @construct_properties argument of - * the @constructor virtual function, the #GParamSpecOverride is passed - * instead, so that the @param_id field of the #GParamSpec will be - * correct. For virtually all uses, this makes no difference. If you - * need to get the overridden property, you can call - * g_param_spec_get_redirect_target(). - * - * Since: 2.4 - */ - - -/** - * g_object_connect: (skip) - * @object: (type GObject.Object): a #GObject - * @signal_spec: the spec for the first signal - * @...: #GCallback for the first signal, followed by data for the - * first signal, followed optionally by more signal - * spec/callback/data triples, followed by %NULL - * - * A convenience function to connect multiple signals at once. - * - * The signal specs expected by this function have the form - * "modifier::signal_name", where modifier can be one of the following: - * - signal: equivalent to g_signal_connect_data (..., NULL, 0) - * - object-signal, object_signal: equivalent to g_signal_connect_object (..., 0) - * - swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED) - * - swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED) - * - signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER) - * - object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER) - * - swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER) - * - swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER) - * - * |[<!-- language="C" --> - * menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, - * "type", GTK_WINDOW_POPUP, - * "child", menu, - * NULL), - * "signal::event", gtk_menu_window_event, menu, - * "signal::size_request", gtk_menu_window_size_request, menu, - * "signal::destroy", gtk_widget_destroyed, &menu->toplevel, - * NULL); - * ]| - * - * Returns: (transfer none) (type GObject.Object): @object - */ - - -/** - * g_object_disconnect: (skip) - * @object: (type GObject.Object): a #GObject - * @signal_spec: the spec for the first signal - * @...: #GCallback for the first signal, followed by data for the first signal, - * followed optionally by more signal spec/callback/data triples, - * followed by %NULL - * - * A convenience function to disconnect multiple signals at once. - * - * The signal specs expected by this function have the form - * "any_signal", which means to disconnect any signal with matching - * callback and data, or "any_signal::signal_name", which only - * disconnects the signal named "signal_name". - */ - - -/** - * g_object_dup_data: (skip) - * @object: the #GObject to store user data on - * @key: a string, naming the user data pointer - * @dup_func: (nullable): function to dup the value - * @user_data: (nullable): passed as user_data to @dup_func - * - * This is a variant of g_object_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 is not set on the object then @dup_func - * will be called with a %NULL argument. - * - * Note that @dup_func is called while user data of @object - * is locked. - * - * This function can be useful to avoid races when multiple - * threads are using object data on the same key on the same - * object. - * - * Returns: the result of calling @dup_func on the value - * associated with @key on @object, or %NULL if not set. - * If @dup_func is %NULL, the value is returned - * unmodified. - * Since: 2.34 - */ - - -/** - * g_object_dup_qdata: (skip) - * @object: the #GObject to store user data on - * @quark: a #GQuark, naming the user data pointer - * @dup_func: (nullable): function to dup the value - * @user_data: (nullable): passed as user_data to @dup_func - * - * This is a variant of g_object_get_qdata() 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 @quark is not set on the object then @dup_func - * will be called with a %NULL argument. - * - * Note that @dup_func is called while user data of @object - * is locked. - * - * This function can be useful to avoid races when multiple - * threads are using object data on the same key on the same - * object. - * - * Returns: the result of calling @dup_func on the value - * associated with @quark on @object, or %NULL if not set. - * If @dup_func is %NULL, the value is returned - * unmodified. - * Since: 2.34 - */ - - -/** - * g_object_force_floating: - * @object: a #GObject - * - * This function is intended for #GObject implementations to re-enforce - * a [floating][floating-ref] object reference. Doing this is seldom - * required: all #GInitiallyUnowneds are created with a floating reference - * which usually just needs to be sunken by calling g_object_ref_sink(). - * - * Since: 2.10 - */ - - -/** - * g_object_freeze_notify: - * @object: a #GObject - * - * Increases the freeze count on @object. If the freeze count is - * non-zero, the emission of "notify" signals on @object is - * stopped. The signals are queued until the freeze count is decreased - * to zero. Duplicate notifications are squashed so that at most one - * #GObject::notify signal is emitted for each property modified while the - * object is frozen. - * - * This is necessary for accessors that modify multiple properties to prevent - * premature notification while the object is still being modified. - */ - - -/** - * g_object_get: (skip) - * @object: (type GObject.Object): a #GObject - * @first_property_name: name of the first property to get - * @...: return location for the first property, followed optionally by more - * name/return location pairs, followed by %NULL - * - * Gets properties of an object. - * - * In general, a copy is made of the property contents and the caller - * is responsible for freeing the memory in the appropriate manner for - * the type, for instance by calling g_free() or g_object_unref(). - * - * Here is an example of using g_object_get() to get the contents - * of three properties: an integer, a string and an object: - * |[<!-- language="C" --> - * gint intval; - * guint64 uint64val; - * gchar *strval; - * GObject *objval; - * - * g_object_get (my_object, - * "int-property", &intval, - * "uint64-property", &uint64val, - * "str-property", &strval, - * "obj-property", &objval, - * NULL); - * - * // Do something with intval, uint64val, strval, objval - * - * g_free (strval); - * g_object_unref (objval); - * ]| - */ - - -/** - * g_object_get_data: - * @object: #GObject containing the associations - * @key: name of the key for that association - * - * Gets a named field from the objects table of associations (see g_object_set_data()). - * - * Returns: (transfer none) (nullable): the data if found, - * or %NULL if no such data exists. - */ - - -/** - * g_object_get_property: - * @object: a #GObject - * @property_name: the name of the property to get - * @value: return location for the property value - * - * Gets a property of an object. - * - * The @value can be: - * - * - an empty #GValue initialized by %G_VALUE_INIT, which will be - * automatically initialized with the expected type of the property - * (since GLib 2.60) - * - a #GValue initialized with the expected type of the property - * - a #GValue initialized with a type to which the expected type - * of the property can be transformed - * - * In general, a copy is made of the property contents and the caller is - * responsible for freeing the memory by calling g_value_unset(). - * - * Note that g_object_get_property() is really intended for language - * bindings, g_object_get() is much more convenient for C programming. - */ - - -/** - * g_object_get_qdata: - * @object: The GObject to get a stored user data pointer from - * @quark: A #GQuark, naming the user data pointer - * - * This function gets back user data pointers stored via - * g_object_set_qdata(). - * - * Returns: (transfer none) (nullable): The user data pointer set, or %NULL - */ - - -/** - * g_object_get_valist: (skip) - * @object: a #GObject - * @first_property_name: name of the first property to get - * @var_args: return location for the first property, followed optionally by more - * name/return location pairs, followed by %NULL - * - * Gets properties of an object. - * - * In general, a copy is made of the property contents and the caller - * is responsible for freeing the memory in the appropriate manner for - * the type, for instance by calling g_free() or g_object_unref(). - * - * See g_object_get(). - */ - - -/** - * g_object_getv: - * @object: a #GObject - * @n_properties: the number of properties - * @names: (array length=n_properties): the names of each property to get - * @values: (array length=n_properties): the values of each property to get - * - * Gets @n_properties properties for an @object. - * Obtained properties will be set to @values. All properties must be valid. - * Warnings will be emitted and undefined behaviour may result if invalid - * properties are passed in. - * - * Since: 2.54 - */ - - -/** - * g_object_interface_find_property: - * @g_iface: (type GObject.TypeInterface): any interface vtable for the - * interface, or the default vtable for the interface - * @property_name: name of a property to look up. - * - * Find the #GParamSpec with the given name for an - * interface. Generally, the interface vtable passed in as @g_iface - * will be the default vtable from g_type_default_interface_ref(), or, - * if you know the interface has already been loaded, - * g_type_default_interface_peek(). - * - * Since: 2.4 - * Returns: (transfer none): the #GParamSpec for the property of the - * interface with the name @property_name, or %NULL if no - * such property exists. - */ - - -/** - * g_object_interface_install_property: - * @g_iface: (type GObject.TypeInterface): any interface vtable for the - * interface, or the default - * vtable for the interface. - * @pspec: the #GParamSpec for the new property - * - * Add a property to an interface; this is only useful for interfaces - * that are added to GObject-derived types. Adding a property to an - * interface forces all objects classes with that interface to have a - * compatible property. The compatible property could be a newly - * created #GParamSpec, but normally - * g_object_class_override_property() will be used so that the object - * class only needs to provide an implementation and inherits the - * property description, default value, bounds, and so forth from the - * interface property. - * - * This function is meant to be called from the interface's default - * vtable initialization function (the @class_init member of - * #GTypeInfo.) It must not be called after after @class_init has - * been called for any object types implementing this interface. - * - * If @pspec is a floating reference, it will be consumed. - * - * Since: 2.4 - */ - - -/** - * g_object_interface_list_properties: - * @g_iface: (type GObject.TypeInterface): any interface vtable for the - * interface, or the default vtable for the interface - * @n_properties_p: (out): location to store number of properties returned. - * - * Lists the properties of an interface.Generally, the interface - * vtable passed in as @g_iface will be the default vtable from - * g_type_default_interface_ref(), or, if you know the interface has - * already been loaded, g_type_default_interface_peek(). - * - * Since: 2.4 - * Returns: (array length=n_properties_p) (transfer container): a - * pointer to an array of pointers to #GParamSpec - * structures. The paramspecs are owned by GLib, but the - * array should be freed with g_free() when you are done with - * it. - */ - - -/** - * g_object_is_floating: - * @object: (type GObject.Object): a #GObject - * - * Checks whether @object has a [floating][floating-ref] reference. - * - * Since: 2.10 - * Returns: %TRUE if @object has a floating reference - */ - - -/** - * g_object_new: (skip) - * @object_type: the type id of the #GObject subtype to instantiate - * @first_property_name: the name of the first property - * @...: the value of the first property, followed optionally by more - * name/value pairs, followed by %NULL - * - * Creates a new instance of a #GObject subtype and sets its properties. - * - * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) - * which are not explicitly specified are set to their default values. Any - * private data for the object is guaranteed to be initialized with zeros, as - * per g_type_create_instance(). - * - * Note that in C, small integer types in variable argument lists are promoted - * up to #gint or #guint as appropriate, and read back accordingly. #gint is 32 - * bits on every platform on which GLib is currently supported. This means that - * you can use C expressions of type #gint with g_object_new() and properties of - * type #gint or #guint or smaller. Specifically, you can use integer literals - * with these property types. - * - * When using property types of #gint64 or #guint64, you must ensure that the - * value that you provide is 64 bit. This means that you should use a cast or - * make use of the %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros. - * - * Similarly, #gfloat is promoted to #gdouble, so you must ensure that the value - * you provide is a #gdouble, even for a property of type #gfloat. - * - * Returns: (transfer full) (type GObject.Object): a new instance of - * @object_type - */ - - -/** - * g_object_new_valist: (skip) - * @object_type: the type id of the #GObject subtype to instantiate - * @first_property_name: the name of the first property - * @var_args: the value of the first property, followed optionally by more - * name/value pairs, followed by %NULL - * - * Creates a new instance of a #GObject subtype and sets its properties. - * - * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) - * which are not explicitly specified are set to their default values. - * - * Returns: a new instance of @object_type - */ - - -/** - * g_object_new_with_properties: (skip) - * @object_type: the object type to instantiate - * @n_properties: the number of properties - * @names: (array length=n_properties): the names of each property to be set - * @values: (array length=n_properties): the values of each property to be set - * - * Creates a new instance of a #GObject subtype and sets its properties using - * the provided arrays. Both arrays must have exactly @n_properties elements, - * and the names and values correspond by index. - * - * Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) - * which are not explicitly specified are set to their default values. - * - * Returns: (type GObject.Object) (transfer full): a new instance of - * @object_type - * Since: 2.54 - */ - - -/** - * g_object_newv: - * @object_type: the type id of the #GObject subtype to instantiate - * @n_parameters: the length of the @parameters array - * @parameters: (array length=n_parameters): an array of #GParameter - * - * Creates a new instance of a #GObject subtype and sets its properties. - * - * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) - * which are not explicitly specified are set to their default values. - * - * Returns: (type GObject.Object) (transfer full): a new instance of - * @object_type - * Deprecated: 2.54: Use g_object_new_with_properties() instead. - * deprecated. See #GParameter for more information. - */ - - -/** - * g_object_notify: - * @object: a #GObject - * @property_name: the name of a property installed on the class of @object. - * - * Emits a "notify" signal for the property @property_name on @object. - * - * When possible, eg. when signaling a property change from within the class - * that registered the property, you should use g_object_notify_by_pspec() - * instead. - * - * Note that emission of the notify signal may be blocked with - * g_object_freeze_notify(). In this case, the signal emissions are queued - * and will be emitted (in reverse order) when g_object_thaw_notify() is - * called. - */ - - -/** - * g_object_notify_by_pspec: - * @object: a #GObject - * @pspec: the #GParamSpec of a property installed on the class of @object. - * - * Emits a "notify" signal for the property specified by @pspec on @object. - * - * This function omits the property name lookup, hence it is faster than - * g_object_notify(). - * - * One way to avoid using g_object_notify() from within the - * class that registered the properties, and using g_object_notify_by_pspec() - * instead, is to store the GParamSpec used with - * g_object_class_install_property() inside a static array, e.g.: - * - * |[<!-- language="C" --> - * enum - * { - * PROP_0, - * PROP_FOO, - * PROP_LAST - * }; - * - * static GParamSpec *properties[PROP_LAST]; - * - * static void - * my_object_class_init (MyObjectClass *klass) - * { - * properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", - * 0, 100, - * 50, - * G_PARAM_READWRITE); - * g_object_class_install_property (gobject_class, - * PROP_FOO, - * properties[PROP_FOO]); - * } - * ]| - * - * and then notify a change on the "foo" property with: - * - * |[<!-- language="C" --> - * g_object_notify_by_pspec (self, properties[PROP_FOO]); - * ]| - * - * Since: 2.26 - */ - - -/** - * g_object_ref: - * @object: (type GObject.Object): a #GObject - * - * Increases the reference count of @object. - * - * Since GLib 2.56, if `GLIB_VERSION_MAX_ALLOWED` is 2.56 or greater, the type - * of @object will be propagated to the return type (using the GCC typeof() - * extension), so any casting the caller needs to do on the return type must be - * explicit. - * - * Returns: (type GObject.Object) (transfer none): the same @object - */ - - -/** - * g_object_ref_sink: - * @object: (type GObject.Object): a #GObject - * - * Increase the reference count of @object, and possibly remove the - * [floating][floating-ref] reference, if @object has a floating reference. - * - * In other words, if the object is floating, then this call "assumes - * ownership" of the floating reference, converting it to a normal - * reference by clearing the floating flag while leaving the reference - * count unchanged. If the object is not floating, then this call - * adds a new normal reference increasing the reference count by one. - * - * Since GLib 2.56, the type of @object will be propagated to the return type - * under the same conditions as for g_object_ref(). - * - * Since: 2.10 - * Returns: (type GObject.Object) (transfer none): @object - */ - - -/** - * g_object_remove_toggle_ref: (skip) - * @object: a #GObject - * @notify: a function to call when this reference is the - * last reference to the object, or is no longer - * the last reference. - * @data: (nullable): data to pass to @notify, or %NULL to - * match any toggle refs with the @notify argument. - * - * Removes a reference added with g_object_add_toggle_ref(). The - * reference count of the object is decreased by one. - * - * Since: 2.8 - */ - - -/** - * g_object_remove_weak_pointer: (skip) - * @object: The object that is weak referenced. - * @weak_pointer_location: (inout) (not optional): The memory address - * of a pointer. - * - * Removes a weak reference from @object that was previously added - * using g_object_add_weak_pointer(). The @weak_pointer_location has - * to match the one used with g_object_add_weak_pointer(). - */ - - -/** - * g_object_replace_data: (skip) - * @object: the #GObject to store user data on - * @key: a string, naming the user data pointer - * @oldval: (nullable): the old value to compare against - * @newval: (nullable): the new value - * @destroy: (nullable): a destroy notify for the new value - * @old_destroy: (out) (optional): destroy notify for the existing value - * - * Compares the user data for the key @key on @object with - * @oldval, and if they are the same, replaces @oldval with - * @newval. - * - * This is like a typical atomic compare-and-exchange - * operation, for user data on an object. - * - * 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). - * It’s up to the caller to free this as needed, which may - * or may not include using @old_destroy as sometimes replacement - * should not destroy the object in the normal way. - * - * See g_object_set_data() for guidance on using a small, bounded set of values - * for @key. - * - * Returns: %TRUE if the existing value for @key was replaced - * by @newval, %FALSE otherwise. - * Since: 2.34 - */ - - -/** - * g_object_replace_qdata: (skip) - * @object: the #GObject to store user data on - * @quark: a #GQuark, naming the user data pointer - * @oldval: (nullable): the old value to compare against - * @newval: (nullable): the new value - * @destroy: (nullable): a destroy notify for the new value - * @old_destroy: (out) (optional): destroy notify for the existing value - * - * Compares the user data for the key @quark on @object with - * @oldval, and if they are the same, replaces @oldval with - * @newval. - * - * This is like a typical atomic compare-and-exchange - * operation, for user data on an object. - * - * 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). - * It’s up to the caller to free this as needed, 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 @quark was replaced - * by @newval, %FALSE otherwise. - * Since: 2.34 - */ - - -/** - * g_object_run_dispose: - * @object: a #GObject - * - * Releases all references to other objects. This can be used to break - * reference cycles. - * - * This function should only be called from object system implementations. - */ - - -/** - * g_object_set: (skip) - * @object: (type GObject.Object): a #GObject - * @first_property_name: name of the first property to set - * @...: value for the first property, followed optionally by more - * name/value pairs, followed by %NULL - * - * Sets properties on an object. - * - * The same caveats about passing integer literals as varargs apply as with - * g_object_new(). In particular, any integer literals set as the values for - * properties of type #gint64 or #guint64 must be 64 bits wide, using the - * %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros. - * - * Note that the "notify" signals are queued and only emitted (in - * reverse order) after all properties have been set. See - * g_object_freeze_notify(). - */ - - -/** - * g_object_set_data: - * @object: #GObject containing the associations. - * @key: name of the key - * @data: (nullable): data to associate with that key - * - * Each object carries around a table of associations from - * strings to pointers. This function lets you set an association. - * - * If the object already had an association with that name, - * the old association will be destroyed. - * - * Internally, the @key is converted to a #GQuark using g_quark_from_string(). - * This means a copy of @key is kept permanently (even after @object has been - * finalized) — so it is recommended to only use a small, bounded set of values - * for @key in your program, to avoid the #GQuark storage growing unbounded. - */ - - -/** - * g_object_set_data_full: (skip) - * @object: #GObject containing the associations - * @key: name of the key - * @data: (nullable): data to associate with that key - * @destroy: (nullable): function to call when the association is destroyed - * - * Like g_object_set_data() except it adds notification - * for when the association is destroyed, either by setting it - * to a different value or when the object is destroyed. - * - * Note that the @destroy callback is not called if @data is %NULL. - */ - - -/** - * g_object_set_property: - * @object: a #GObject - * @property_name: the name of the property to set - * @value: the value - * - * Sets a property on an object. - */ - - -/** - * g_object_set_qdata: (skip) - * @object: The GObject to set store a user data pointer - * @quark: A #GQuark, naming the user data pointer - * @data: (nullable): An opaque user data pointer - * - * This sets an opaque, named pointer on an object. - * The name is specified through a #GQuark (retrieved e.g. via - * g_quark_from_static_string()), and the pointer - * can be gotten back from the @object with g_object_get_qdata() - * until the @object is finalized. - * Setting a previously set user data pointer, overrides (frees) - * the old pointer set, using #NULL as pointer essentially - * removes the data stored. - */ - - -/** - * g_object_set_qdata_full: (skip) - * @object: The GObject to set store a user data pointer - * @quark: A #GQuark, naming the user data pointer - * @data: (nullable): An opaque user data pointer - * @destroy: (nullable): Function to invoke with @data as argument, when @data - * needs to be freed - * - * This function works like g_object_set_qdata(), but in addition, - * a void (*destroy) (gpointer) function may be specified which is - * called with @data as argument when the @object is finalized, or - * the data is being overwritten by a call to g_object_set_qdata() - * with the same @quark. - */ - - -/** - * g_object_set_valist: (skip) - * @object: a #GObject - * @first_property_name: name of the first property to set - * @var_args: value for the first property, followed optionally by more - * name/value pairs, followed by %NULL - * - * Sets properties on an object. - */ - - -/** - * g_object_setv: (skip) - * @object: a #GObject - * @n_properties: the number of properties - * @names: (array length=n_properties): the names of each property to be set - * @values: (array length=n_properties): the values of each property to be set - * - * Sets @n_properties properties for an @object. - * Properties to be set will be taken from @values. All properties must be - * valid. Warnings will be emitted and undefined behaviour may result if invalid - * properties are passed in. - * - * Since: 2.54 - */ - - -/** - * g_object_steal_data: - * @object: #GObject containing the associations - * @key: name of the key - * - * Remove a specified datum from the object's data associations, - * without invoking the association's destroy handler. - * - * Returns: (transfer full) (nullable): the data if found, or %NULL - * if no such data exists. - */ - - -/** - * g_object_steal_qdata: - * @object: The GObject to get a stored user data pointer from - * @quark: A #GQuark, naming the user data pointer - * - * This function gets back user data pointers stored via - * g_object_set_qdata() and removes the @data from object - * without invoking its destroy() function (if any was - * set). - * Usually, calling this function is only required to update - * user data pointers with a destroy notifier, for example: - * |[<!-- language="C" --> - * void - * object_add_to_user_list (GObject *object, - * const gchar *new_string) - * { - * // the quark, naming the object data - * GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); - * // retrieve the old string list - * GList *list = g_object_steal_qdata (object, quark_string_list); - * - * // prepend new string - * list = g_list_prepend (list, g_strdup (new_string)); - * // this changed 'list', so we need to set it again - * g_object_set_qdata_full (object, quark_string_list, list, free_string_list); - * } - * static void - * free_string_list (gpointer data) - * { - * GList *node, *list = data; - * - * for (node = list; node; node = node->next) - * g_free (node->data); - * g_list_free (list); - * } - * ]| - * Using g_object_get_qdata() in the above example, instead of - * g_object_steal_qdata() would have left the destroy function set, - * and thus the partial string list would have been freed upon - * g_object_set_qdata_full(). - * - * Returns: (transfer full) (nullable): The user data pointer set, or %NULL - */ - - -/** - * g_object_take_ref: (skip) - * @object: (type GObject.Object): a #GObject - * - * If @object is floating, sink it. Otherwise, do nothing. - * - * In other words, this function will convert a floating reference (if - * present) into a full reference. - * - * Typically you want to use g_object_ref_sink() in order to - * automatically do the correct thing with respect to floating or - * non-floating references, but there is one specific scenario where - * this function is helpful. - * - * The situation where this function is helpful is when creating an API - * that allows the user to provide a callback function that returns a - * GObject. We certainly want to allow the user the flexibility to - * return a non-floating reference from this callback (for the case - * where the object that is being returned already exists). - * - * At the same time, the API style of some popular GObject-based - * libraries (such as Gtk) make it likely that for newly-created GObject - * instances, the user can be saved some typing if they are allowed to - * return a floating reference. - * - * Using this function on the return value of the user's callback allows - * the user to do whichever is more convenient for them. The caller will - * alway receives exactly one full reference to the value: either the - * one that was returned in the first place, or a floating reference - * that has been converted to a full reference. - * - * This function has an odd interaction when combined with - * g_object_ref_sink() running at the same time in another thread on - * the same #GObject instance. If g_object_ref_sink() runs first then - * the result will be that the floating reference is converted to a hard - * reference. If g_object_take_ref() runs first then the result will be - * that the floating reference is converted to a hard reference and an - * additional reference on top of that one is added. It is best to avoid - * this situation. - * - * Since: 2.70 - * Returns: (type GObject.Object) (transfer full): @object - */ - - -/** - * g_object_thaw_notify: - * @object: a #GObject - * - * Reverts the effect of a previous call to - * g_object_freeze_notify(). The freeze count is decreased on @object - * and when it reaches zero, queued "notify" signals are emitted. - * - * Duplicate notifications for each property are squashed so that at most one - * #GObject::notify signal is emitted for each property, in the reverse order - * in which they have been queued. - * - * It is an error to call this function when the freeze count is zero. - */ - - -/** - * g_object_unref: - * @object: (type GObject.Object): a #GObject - * - * Decreases the reference count of @object. When its reference count - * drops to 0, the object is finalized (i.e. its memory is freed). - * - * If the pointer to the #GObject may be reused in future (for example, if it is - * an instance variable of another object), it is recommended to clear the - * pointer to %NULL rather than retain a dangling pointer to a potentially - * invalid #GObject instance. Use g_clear_object() for this. - */ - - -/** - * g_object_watch_closure: - * @object: #GObject restricting lifetime of @closure - * @closure: #GClosure to watch - * - * This function essentially limits the life time of the @closure to - * the life time of the object. That is, when the object is finalized, - * the @closure is invalidated by calling g_closure_invalidate() on - * it, in order to prevent invocations of the closure with a finalized - * (nonexisting) object. Also, g_object_ref() and g_object_unref() are - * added as marshal guards to the @closure, to ensure that an extra - * reference count is held on @object during invocation of the - * @closure. Usually, this function will be called on closures that - * use this @object as closure data. - */ - - -/** - * g_object_weak_ref: (skip) - * @object: #GObject to reference weakly - * @notify: callback to invoke before the object is freed - * @data: extra data to pass to notify - * - * Adds a weak reference callback to an object. Weak references are - * used for notification when an object is disposed. They are called - * "weak references" because they allow you to safely hold a pointer - * to an object without calling g_object_ref() (g_object_ref() adds a - * strong reference, that is, forces the object to stay alive). - * - * Note that the weak references created by this method are not - * thread-safe: they cannot safely be used in one thread if the - * object's last g_object_unref() might happen in another thread. - * Use #GWeakRef if thread-safety is required. - */ - - -/** - * g_object_weak_unref: (skip) - * @object: #GObject to remove a weak reference from - * @notify: callback to search for - * @data: data to search for - * - * Removes a weak reference callback to an object. - */ - - -/** - * g_param_spec_boolean: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN - * property. In many cases, it may be more appropriate to use an enum with - * g_param_spec_enum(), both to improve code clarity by using explicitly named - * values, and to allow for more values to be added in future without breaking - * API. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_boxed: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @boxed_type: %G_TYPE_BOXED derived type of this property - * @flags: flags for the property specified - * - * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED - * derived property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_char: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_double: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE - * property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_enum: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @enum_type: a #GType derived from %G_TYPE_ENUM - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM - * property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_flags: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @flags_type: a #GType derived from %G_TYPE_FLAGS - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS - * property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_float: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_get_blurb: - * @pspec: a valid #GParamSpec - * - * Get the short description of a #GParamSpec. - * - * Returns: (nullable): the short description of @pspec. - */ - - -/** - * g_param_spec_get_default_value: - * @pspec: a #GParamSpec - * - * Gets the default value of @pspec as a pointer to a #GValue. - * - * The #GValue will remain valid for the life of @pspec. - * - * Returns: a pointer to a #GValue which must not be modified - * Since: 2.38 - */ - - -/** - * g_param_spec_get_name: - * @pspec: a valid #GParamSpec - * - * Get the name of a #GParamSpec. - * - * The name is always an "interned" string (as per g_intern_string()). - * This allows for pointer-value comparisons. - * - * Returns: the name of @pspec. - */ - - -/** - * g_param_spec_get_name_quark: - * @pspec: a #GParamSpec - * - * Gets the GQuark for the name. - * - * Returns: the GQuark for @pspec->name. - * Since: 2.46 - */ - - -/** - * g_param_spec_get_nick: - * @pspec: a valid #GParamSpec - * - * Get the nickname of a #GParamSpec. - * - * Returns: the nickname of @pspec. - */ - - -/** - * g_param_spec_get_qdata: - * @pspec: a valid #GParamSpec - * @quark: a #GQuark, naming the user data pointer - * - * Gets back user data pointers stored via g_param_spec_set_qdata(). - * - * Returns: (transfer none) (nullable): the user data pointer set, or %NULL - */ - - -/** - * g_param_spec_get_redirect_target: - * @pspec: a #GParamSpec - * - * If the paramspec redirects operations to another paramspec, - * returns that paramspec. Redirect is used typically for - * providing a new implementation of a property in a derived - * type while preserving all the properties from the parent - * type. Redirection is established by creating a property - * of type #GParamSpecOverride. See g_object_class_override_property() - * for an example of the use of this capability. - * - * Since: 2.4 - * Returns: (transfer none) (nullable): paramspec to which requests on this - * paramspec should be redirected, or %NULL if none. - */ - - -/** - * g_param_spec_gtype: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @is_a_type: a #GType whose subtypes are allowed as values - * of the property (use %G_TYPE_NONE for any type) - * @flags: flags for the property specified - * - * Creates a new #GParamSpecGType instance specifying a - * %G_TYPE_GTYPE property. - * - * See g_param_spec_internal() for details on property names. - * - * Since: 2.10 - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_int: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_int64: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_internal: (skip) - * @param_type: the #GType for the property; must be derived from #G_TYPE_PARAM - * @name: the canonical name of the property - * @nick: the nickname of the property - * @blurb: a short description of the property - * @flags: a combination of #GParamFlags - * - * Creates a new #GParamSpec instance. - * - * See [canonical parameter names][canonical-parameter-names] for details of - * the rules for @name. Names which violate these rules lead to undefined - * behaviour. - * - * Beyond the name, #GParamSpecs have two more descriptive - * strings associated with them, the @nick, which should be suitable - * for use as a label for the property in a property editor, and the - * @blurb, which should be a somewhat longer description, suitable for - * e.g. a tooltip. The @nick and @blurb should ideally be localized. - * - * Returns: (type GObject.ParamSpec): (transfer floating): a newly allocated - * #GParamSpec instance, which is initially floating - */ - - -/** - * g_param_spec_is_valid_name: - * @name: the canonical name of the property - * - * Validate a property name for a #GParamSpec. This can be useful for - * dynamically-generated properties which need to be validated at run-time - * before actually trying to create them. - * - * See [canonical parameter names][canonical-parameter-names] for details of - * the rules for valid names. - * - * Returns: %TRUE if @name is a valid property name, %FALSE otherwise. - * Since: 2.66 - */ - - -/** - * g_param_spec_long: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_object: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @object_type: %G_TYPE_OBJECT derived type of this property - * @flags: flags for the property specified - * - * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT - * derived property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_override: (skip) - * @name: the name of the property. - * @overridden: The property that is being overridden - * - * Creates a new property of type #GParamSpecOverride. This is used - * to direct operations to another paramspec, and will not be directly - * useful unless you are implementing a new base type similar to GObject. - * - * Since: 2.4 - * Returns: the newly created #GParamSpec - */ - - -/** - * g_param_spec_param: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @param_type: a #GType derived from %G_TYPE_PARAM - * @flags: flags for the property specified - * - * Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM - * property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_pointer: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecPointer instance specifying a pointer property. - * Where possible, it is better to use g_param_spec_object() or - * g_param_spec_boxed() to expose memory management information. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_pool_insert: - * @pool: a #GParamSpecPool. - * @pspec: (transfer none) (not nullable): the #GParamSpec to insert - * @owner_type: a #GType identifying the owner of @pspec - * - * Inserts a #GParamSpec in the pool. - */ - - -/** - * g_param_spec_pool_list: - * @pool: a #GParamSpecPool - * @owner_type: the owner to look for - * @n_pspecs_p: (out): return location for the length of the returned array - * - * Gets an array of all #GParamSpecs owned by @owner_type in - * the pool. - * - * Returns: (array length=n_pspecs_p) (transfer container): a newly - * allocated array containing pointers to all #GParamSpecs - * owned by @owner_type in the pool - */ - - -/** - * g_param_spec_pool_list_owned: - * @pool: a #GParamSpecPool - * @owner_type: the owner to look for - * - * Gets an #GList of all #GParamSpecs owned by @owner_type in - * the pool. - * - * Returns: (transfer container) (element-type GObject.ParamSpec): a - * #GList of all #GParamSpecs owned by @owner_type in - * the pool#GParamSpecs. - */ - - -/** - * g_param_spec_pool_lookup: - * @pool: a #GParamSpecPool - * @param_name: the name to look for - * @owner_type: the owner to look for - * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name - * owned by an ancestor of @owner_type. - * - * Looks up a #GParamSpec in the pool. - * - * Returns: (transfer none) (nullable): The found #GParamSpec, or %NULL if no - * matching #GParamSpec was found. - */ - - -/** - * g_param_spec_pool_new: - * @type_prefixing: Whether the pool will support type-prefixed property names. - * - * Creates a new #GParamSpecPool. - * - * If @type_prefixing is %TRUE, lookups in the newly created pool will - * allow to specify the owner as a colon-separated prefix of the - * property name, like "GtkContainer:border-width". This feature is - * deprecated, so you should always set @type_prefixing to %FALSE. - * - * Returns: (transfer full): a newly allocated #GParamSpecPool. - */ - - -/** - * g_param_spec_pool_remove: - * @pool: a #GParamSpecPool - * @pspec: (transfer none) (not nullable): the #GParamSpec to remove - * - * Removes a #GParamSpec from the pool. - */ - - -/** - * g_param_spec_ref: (skip) - * @pspec: (transfer none) (not nullable): a valid #GParamSpec - * - * Increments the reference count of @pspec. - * - * Returns: (transfer full) (not nullable): the #GParamSpec that was passed into this function - */ - - -/** - * g_param_spec_ref_sink: (skip) - * @pspec: a valid #GParamSpec - * - * Convenience function to ref and sink a #GParamSpec. - * - * Since: 2.10 - * Returns: (transfer full) (not nullable): the #GParamSpec that was passed into this function - */ - - -/** - * g_param_spec_set_qdata: - * @pspec: the #GParamSpec to set store a user data pointer - * @quark: a #GQuark, naming the user data pointer - * @data: (nullable): an opaque user data pointer - * - * Sets an opaque, named pointer on a #GParamSpec. The name is - * specified through a #GQuark (retrieved e.g. via - * g_quark_from_static_string()), and the pointer can be gotten back - * from the @pspec with g_param_spec_get_qdata(). Setting a - * previously set user data pointer, overrides (frees) the old pointer - * set, using %NULL as pointer essentially removes the data stored. - */ - - -/** - * g_param_spec_set_qdata_full: (skip) - * @pspec: the #GParamSpec to set store a user data pointer - * @quark: a #GQuark, naming the user data pointer - * @data: (nullable): an opaque user data pointer - * @destroy: (nullable): function to invoke with @data as argument, when @data needs to - * be freed - * - * This function works like g_param_spec_set_qdata(), but in addition, - * a `void (*destroy) (gpointer)` function may be - * specified which is called with @data as argument when the @pspec is - * finalized, or the data is being overwritten by a call to - * g_param_spec_set_qdata() with the same @quark. - */ - - -/** - * g_param_spec_sink: - * @pspec: a valid #GParamSpec - * - * The initial reference count of a newly created #GParamSpec is 1, - * even though no one has explicitly called g_param_spec_ref() on it - * yet. So the initial reference count is flagged as "floating", until - * someone calls `g_param_spec_ref (pspec); g_param_spec_sink - * (pspec);` in sequence on it, taking over the initial - * reference count (thus ending up with a @pspec that has a reference - * count of 1 still, but is not flagged "floating" anymore). - */ - - -/** - * g_param_spec_steal_qdata: - * @pspec: the #GParamSpec to get a stored user data pointer from - * @quark: a #GQuark, naming the user data pointer - * - * Gets back user data pointers stored via g_param_spec_set_qdata() - * and removes the @data from @pspec without invoking its destroy() - * function (if any was set). Usually, calling this function is only - * required to update user data pointers with a destroy notifier. - * - * Returns: (transfer none) (nullable): the user data pointer set, or %NULL - */ - - -/** - * g_param_spec_string: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @default_value: (nullable): default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecString instance. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_uchar: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_uint: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_uint64: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 - * property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_ulong: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG - * property. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_unichar: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT - * property. #GValue structures for this property can be accessed with - * g_value_set_uint() and g_value_get_uint(). - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): a newly created parameter specification - */ - - -/** - * g_param_spec_unref: (skip) - * @pspec: a valid #GParamSpec - * - * Decrements the reference count of a @pspec. - */ - - -/** - * g_param_spec_value_array: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @element_spec: a #GParamSpec describing the elements contained in - * arrays of this property, may be %NULL - * @flags: flags for the property specified - * - * Creates a new #GParamSpecValueArray instance specifying a - * %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a - * %G_TYPE_BOXED type, as such, #GValue structures for this property - * can be accessed with g_value_set_boxed() and g_value_get_boxed(). - * - * See g_param_spec_internal() for details on property names. - * - * Returns: a newly created parameter specification - */ - - -/** - * g_param_spec_variant: - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @type: a #GVariantType - * @default_value: (nullable) (transfer full): a #GVariant of type @type to - * use as the default value, or %NULL - * @flags: flags for the property specified - * - * Creates a new #GParamSpecVariant instance specifying a #GVariant - * property. - * - * If @default_value is floating, it is consumed. - * - * See g_param_spec_internal() for details on property names. - * - * Returns: (transfer full): the newly created #GParamSpec - * Since: 2.26 - */ - - -/** - * g_param_type_register_static: - * @name: 0-terminated string used as the name of the new #GParamSpec type. - * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. - * - * Registers @name as the name of a new static type derived - * from #G_TYPE_PARAM. - * - * The type system uses the information contained in the #GParamSpecTypeInfo - * structure pointed to by @info to manage the #GParamSpec type and its - * instances. - * - * Returns: The new type identifier. - */ - - -/** - * g_param_value_convert: - * @pspec: a valid #GParamSpec - * @src_value: source #GValue - * @dest_value: destination #GValue of correct type for @pspec - * @strict_validation: %TRUE requires @dest_value to conform to @pspec - * without modifications - * - * Transforms @src_value into @dest_value if possible, and then - * validates @dest_value, in order for it to conform to @pspec. If - * @strict_validation is %TRUE this function will only succeed if the - * transformed @dest_value complied to @pspec without modifications. - * - * See also g_value_type_transformable(), g_value_transform() and - * g_param_value_validate(). - * - * Returns: %TRUE if transformation and validation were successful, - * %FALSE otherwise and @dest_value is left untouched. - */ - - -/** - * g_param_value_defaults: - * @pspec: a valid #GParamSpec - * @value: a #GValue of correct type for @pspec - * - * Checks whether @value contains the default value as specified in @pspec. - * - * Returns: whether @value contains the canonical default for this @pspec - */ - - -/** - * g_param_value_set_default: - * @pspec: a valid #GParamSpec - * @value: a #GValue of correct type for @pspec; since 2.64, you - * can also pass an empty #GValue, initialized with %G_VALUE_INIT - * - * Sets @value to its default value as specified in @pspec. - */ - - -/** - * g_param_value_validate: - * @pspec: a valid #GParamSpec - * @value: a #GValue of correct type for @pspec - * - * Ensures that the contents of @value comply with the specifications - * set out by @pspec. For example, a #GParamSpecInt might require - * that integers stored in @value may not be smaller than -42 and not be - * greater than +42. If @value contains an integer outside of this range, - * it is modified accordingly, so the resulting value will fit into the - * range -42 .. +42. - * - * Returns: whether modifying @value was necessary to ensure validity - */ - - -/** - * g_param_values_cmp: - * @pspec: a valid #GParamSpec - * @value1: a #GValue of correct type for @pspec - * @value2: a #GValue of correct type for @pspec - * - * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, - * if @value1 is found to be less than, equal to or greater than @value2, - * respectively. - * - * Returns: -1, 0 or +1, for a less than, equal to or greater than result - */ - - -/** - * g_pointer_type_register_static: - * @name: the name of the new pointer type. - * - * Creates a new %G_TYPE_POINTER derived type id for a new - * pointer type with name @name. - * - * Returns: a new %G_TYPE_POINTER derived type id for @name. - */ - - -/** - * g_signal_accumulator_first_wins: - * @ihint: standard #GSignalAccumulator parameter - * @return_accu: standard #GSignalAccumulator parameter - * @handler_return: standard #GSignalAccumulator parameter - * @dummy: standard #GSignalAccumulator parameter - * - * A predefined #GSignalAccumulator for signals intended to be used as a - * hook for application code to provide a particular value. Usually - * only one such value is desired and multiple handlers for the same - * signal don't make much sense (except for the case of the default - * handler defined in the class structure, in which case you will - * usually want the signal connection to override the class handler). - * - * This accumulator will use the return value from the first signal - * handler that is run as the return value for the signal and not run - * any further handlers (ie: the first handler "wins"). - * - * Returns: standard #GSignalAccumulator result - * Since: 2.28 - */ - - -/** - * g_signal_accumulator_true_handled: - * @ihint: standard #GSignalAccumulator parameter - * @return_accu: standard #GSignalAccumulator parameter - * @handler_return: standard #GSignalAccumulator parameter - * @dummy: standard #GSignalAccumulator parameter - * - * A predefined #GSignalAccumulator for signals that return a - * boolean values. The behavior that this accumulator gives is - * that a return of %TRUE stops the signal emission: no further - * callbacks will be invoked, while a return of %FALSE allows - * the emission to continue. The idea here is that a %TRUE return - * indicates that the callback handled the signal, and no further - * handling is needed. - * - * Since: 2.4 - * Returns: standard #GSignalAccumulator result - */ - - -/** - * g_signal_add_emission_hook: - * @signal_id: the signal identifier, as returned by g_signal_lookup(). - * @detail: the detail on which to call the hook. - * @hook_func: (not nullable): a #GSignalEmissionHook function. - * @hook_data: (nullable) (closure hook_func): user data for @hook_func. - * @data_destroy: (nullable) (destroy hook_data): a #GDestroyNotify for @hook_data. - * - * Adds an emission hook for a signal, which will get called for any emission - * of that signal, independent of the instance. This is possible only - * for signals which don't have #G_SIGNAL_NO_HOOKS flag set. - * - * Returns: the hook id, for later use with g_signal_remove_emission_hook(). - */ - - -/** - * g_signal_chain_from_overridden: - * @instance_and_params: (array): the argument list of the signal emission. - * The first element in the array is a #GValue for the instance the signal - * is being emitted on. The rest are any arguments to be passed to the signal. - * @return_value: Location for the return value. - * - * Calls the original class closure of a signal. This function should only - * be called from an overridden class closure; see - * g_signal_override_class_closure() and - * g_signal_override_class_handler(). - */ - - -/** - * g_signal_chain_from_overridden_handler: (skip) - * @instance: (type GObject.TypeInstance): the instance the signal is being - * emitted on. - * @...: parameters to be passed to the parent class closure, followed by a - * location for the return value. If the return type of the signal - * is #G_TYPE_NONE, the return value location can be omitted. - * - * Calls the original class closure of a signal. This function should - * only be called from an overridden class closure; see - * g_signal_override_class_closure() and - * g_signal_override_class_handler(). - * - * Since: 2.18 - */ - - -/** - * g_signal_connect_closure: - * @instance: (type GObject.Object): the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @closure: (not nullable): the closure to connect. - * @after: whether the handler should be called before or after the - * default handler of the signal. - * - * Connects a closure to a signal for a particular object. - * - * Returns: the handler ID (always greater than 0 for successful connections) - */ - - -/** - * g_signal_connect_closure_by_id: - * @instance: (type GObject.Object): the instance to connect to. - * @signal_id: the id of the signal. - * @detail: the detail. - * @closure: (not nullable): the closure to connect. - * @after: whether the handler should be called before or after the - * default handler of the signal. - * - * Connects a closure to a signal for a particular object. - * - * Returns: the handler ID (always greater than 0 for successful connections) - */ - - -/** - * g_signal_connect_data: - * @instance: (type GObject.Object): the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: (not nullable): the #GCallback to connect. - * @data: (nullable) (closure c_handler): data to pass to @c_handler calls. - * @destroy_data: (nullable) (destroy data): a #GClosureNotify for @data. - * @connect_flags: a combination of #GConnectFlags. - * - * Connects a #GCallback function to a signal for a particular object. Similar - * to g_signal_connect(), but allows to provide a #GClosureNotify for the data - * which will be called when the signal handler is disconnected and no longer - * used. Specify @connect_flags if you need `..._after()` or - * `..._swapped()` variants of this function. - * - * Returns: the handler ID (always greater than 0 for successful connections) - */ - - -/** - * g_signal_connect_object: (skip) - * @instance: (type GObject.TypeInstance): the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @gobject: (type GObject.Object) (nullable): the object to pass as data - * to @c_handler. - * @connect_flags: a combination of #GConnectFlags. - * - * This is similar to g_signal_connect_data(), but uses a closure which - * ensures that the @gobject stays alive during the call to @c_handler - * by temporarily adding a reference count to @gobject. - * - * When the @gobject is destroyed the signal handler will be automatically - * disconnected. Note that this is not currently threadsafe (ie: - * emitting a signal while @gobject is being destroyed in another thread - * is not safe). - * - * Returns: the handler id. - */ - - -/** - * g_signal_emit: - * @instance: (type GObject.Object): the instance the signal is being emitted on. - * @signal_id: the signal id - * @detail: the detail - * @...: parameters to be passed to the signal, followed by a - * location for the return value. If the return type of the signal - * is #G_TYPE_NONE, the return value location can be omitted. - * - * Emits a signal. - * - * Note that g_signal_emit() resets the return value to the default - * if no handlers are connected, in contrast to g_signal_emitv(). - */ - - -/** - * g_signal_emit_by_name: - * @instance: (type GObject.Object): the instance the signal is being emitted on. - * @detailed_signal: a string of the form "signal-name::detail". - * @...: parameters to be passed to the signal, followed by a - * location for the return value. If the return type of the signal - * is %G_TYPE_NONE, the return value location can be omitted. The - * number of parameters to pass to this function is defined when creating the signal. - * - * Emits a signal. - * - * Note that g_signal_emit_by_name() resets the return value to the default - * if no handlers are connected, in contrast to g_signal_emitv(). - */ - - -/** - * g_signal_emit_valist: (skip) - * @instance: (type GObject.TypeInstance): the instance the signal is being - * emitted on. - * @signal_id: the signal id - * @detail: the detail - * @var_args: a list of parameters to be passed to the signal, followed by a - * location for the return value. If the return type of the signal - * is #G_TYPE_NONE, the return value location can be omitted. - * - * Emits a signal. - * - * Note that g_signal_emit_valist() resets the return value to the default - * if no handlers are connected, in contrast to g_signal_emitv(). - */ - - -/** - * g_signal_emitv: - * @instance_and_params: (array): argument list for the signal emission. - * The first element in the array is a #GValue for the instance the signal - * is being emitted on. The rest are any arguments to be passed to the signal. - * @signal_id: the signal id - * @detail: the detail - * @return_value: (inout) (optional): Location to - * store the return value of the signal emission. This must be provided if the - * specified signal returns a value, but may be ignored otherwise. - * - * Emits a signal. - * - * Note that g_signal_emitv() doesn't change @return_value if no handlers are - * connected, in contrast to g_signal_emit() and g_signal_emit_valist(). - */ - - -/** - * g_signal_get_invocation_hint: - * @instance: (type GObject.Object): the instance to query - * - * Returns the invocation hint of the innermost signal emission of instance. - * - * Returns: (transfer none) (nullable): the invocation hint of the innermost - * signal emission, or %NULL if not found. - */ - - -/** - * g_signal_handler_block: - * @instance: (type GObject.Object): The instance to block the signal handler of. - * @handler_id: Handler id of the handler to be blocked. - * - * Blocks a handler of an instance so it will not be called during any - * signal emissions unless it is unblocked again. Thus "blocking" a - * signal handler means to temporarily deactivate it, a signal handler - * has to be unblocked exactly the same amount of times it has been - * blocked before to become active again. - * - * The @handler_id has to be a valid signal handler id, connected to a - * signal of @instance. - */ - - -/** - * g_signal_handler_disconnect: - * @instance: (type GObject.Object): The instance to remove the signal handler from. - * @handler_id: Handler id of the handler to be disconnected. - * - * Disconnects a handler from an instance so it will not be called during - * any future or currently ongoing emissions of the signal it has been - * connected to. The @handler_id becomes invalid and may be reused. - * - * The @handler_id has to be a valid signal handler id, connected to a - * signal of @instance. - */ - - -/** - * g_signal_handler_find: - * @instance: (type GObject.Object): The instance owning the signal handler to be found. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func - * and/or @data the handler has to match. - * @signal_id: Signal the handler has to be connected to. - * @detail: Signal detail the handler has to be connected to. - * @closure: (nullable): The closure the handler will invoke. - * @func: The C closure callback of the handler (useless for non-C closures). - * @data: (nullable) (closure closure): The closure data of the handler's closure. - * - * Finds the first signal handler that matches certain selection criteria. - * The criteria mask is passed as an OR-ed combination of #GSignalMatchType - * flags, and the criteria values are passed as arguments. - * The match @mask has to be non-0 for successful matches. - * If no handler was found, 0 is returned. - * - * Returns: A valid non-0 signal handler id for a successful match. - */ - - -/** - * g_signal_handler_is_connected: - * @instance: (type GObject.Object): The instance where a signal handler is sought. - * @handler_id: the handler ID. - * - * Returns whether @handler_id is the ID of a handler connected to @instance. - * - * Returns: whether @handler_id identifies a handler connected to @instance. - */ - - -/** - * g_signal_handler_unblock: - * @instance: (type GObject.Object): The instance to unblock the signal handler of. - * @handler_id: Handler id of the handler to be unblocked. - * - * Undoes the effect of a previous g_signal_handler_block() call. A - * blocked handler is skipped during signal emissions and will not be - * invoked, unblocking it (for exactly the amount of times it has been - * blocked before) reverts its "blocked" state, so the handler will be - * recognized by the signal system and is called upon future or - * currently ongoing signal emissions (since the order in which - * handlers are called during signal emissions is deterministic, - * whether the unblocked handler in question is called as part of a - * currently ongoing emission depends on how far that emission has - * proceeded yet). - * - * The @handler_id has to be a valid id of a signal handler that is - * connected to a signal of @instance and is currently blocked. - */ - - -/** - * g_signal_handlers_block_matched: - * @instance: (type GObject.Object): The instance to block handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func - * and/or @data the handlers have to match. - * @signal_id: Signal the handlers have to be connected to. - * @detail: Signal detail the handlers have to be connected to. - * @closure: (nullable): The closure the handlers will invoke. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: (nullable) (closure closure): The closure data of the handlers' closures. - * - * Blocks all handlers on an instance that match a certain selection criteria. - * The criteria mask is passed as an OR-ed combination of #GSignalMatchType - * flags, and the criteria values are passed as arguments. - * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC - * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. - * If no handlers were found, 0 is returned, the number of blocked handlers - * otherwise. - * - * Returns: The number of handlers that matched. - */ - - -/** - * g_signal_handlers_destroy: - * @instance: (type GObject.Object): The instance whose signal handlers are destroyed - * - * Destroy all signal handlers of a type instance. This function is - * an implementation detail of the #GObject dispose implementation, - * and should not be used outside of the type system. - */ - - -/** - * g_signal_handlers_disconnect_matched: - * @instance: (type GObject.Object): The instance to remove handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func - * and/or @data the handlers have to match. - * @signal_id: Signal the handlers have to be connected to. - * @detail: Signal detail the handlers have to be connected to. - * @closure: (nullable): The closure the handlers will invoke. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: (nullable) (closure closure): The closure data of the handlers' closures. - * - * Disconnects all handlers on an instance that match a certain - * selection criteria. The criteria mask is passed as an OR-ed - * combination of #GSignalMatchType flags, and the criteria values are - * passed as arguments. Passing at least one of the - * %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or - * %G_SIGNAL_MATCH_DATA match flags is required for successful - * matches. If no handlers were found, 0 is returned, the number of - * disconnected handlers otherwise. - * - * Returns: The number of handlers that matched. - */ - - -/** - * g_signal_handlers_unblock_matched: - * @instance: (type GObject.Object): The instance to unblock handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func - * and/or @data the handlers have to match. - * @signal_id: Signal the handlers have to be connected to. - * @detail: Signal detail the handlers have to be connected to. - * @closure: (nullable): The closure the handlers will invoke. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: (nullable) (closure closure): The closure data of the handlers' closures. - * - * Unblocks all handlers on an instance that match a certain selection - * criteria. The criteria mask is passed as an OR-ed combination of - * #GSignalMatchType flags, and the criteria values are passed as arguments. - * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC - * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. - * If no handlers were found, 0 is returned, the number of unblocked handlers - * otherwise. The match criteria should not apply to any handlers that are - * not currently blocked. - * - * Returns: The number of handlers that matched. - */ - - -/** - * g_signal_has_handler_pending: - * @instance: (type GObject.Object): the object whose signal handlers are sought. - * @signal_id: the signal id. - * @detail: the detail. - * @may_be_blocked: whether blocked handlers should count as match. - * - * Returns whether there are any handlers connected to @instance for the - * given signal id and detail. - * - * If @detail is 0 then it will only match handlers that were connected - * without detail. If @detail is non-zero then it will match handlers - * connected both without detail and with the given detail. This is - * consistent with how a signal emitted with @detail would be delivered - * to those handlers. - * - * Since 2.46 this also checks for a non-default class closure being - * installed, as this is basically always what you want. - * - * One example of when you might use this is when the arguments to the - * signal are difficult to compute. A class implementor may opt to not - * emit the signal if no one is attached anyway, thus saving the cost - * of building the arguments. - * - * Returns: %TRUE if a handler is connected to the signal, %FALSE - * otherwise. - */ - - -/** - * g_signal_is_valid_name: - * @name: the canonical name of the signal - * - * Validate a signal name. This can be useful for dynamically-generated signals - * which need to be validated at run-time before actually trying to create them. - * - * See [canonical parameter names][canonical-parameter-names] for details of - * the rules for valid names. The rules for signal names are the same as those - * for property names. - * - * Returns: %TRUE if @name is a valid signal name, %FALSE otherwise. - * Since: 2.66 - */ - - -/** - * g_signal_list_ids: - * @itype: Instance or interface type. - * @n_ids: Location to store the number of signal ids for @itype. - * - * Lists the signals by id that a certain instance or interface type - * created. Further information about the signals can be acquired through - * g_signal_query(). - * - * Returns: (array length=n_ids) (transfer full): Newly allocated array of signal IDs. - */ - - -/** - * g_signal_lookup: - * @name: the signal's name. - * @itype: the type that the signal operates on. - * - * Given the name of the signal and the type of object it connects to, gets - * the signal's identifying integer. Emitting the signal by number is - * somewhat faster than using the name each time. - * - * Also tries the ancestors of the given type. - * - * The type class passed as @itype must already have been instantiated (for - * example, using g_type_class_ref()) for this function to work, as signals are - * always installed during class initialization. - * - * See g_signal_new() for details on allowed signal names. - * - * Returns: the signal's identifying number, or 0 if no signal was found. - */ - - -/** - * g_signal_name: - * @signal_id: the signal's identifying number. - * - * Given the signal's identifier, finds its name. - * - * Two different signals may have the same name, if they have differing types. - * - * Returns: (nullable): the signal name, or %NULL if the signal number was invalid. - */ - - -/** - * g_signal_new: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to - * types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when - * the default handler is to be invoked. You should at least specify - * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_offset: The offset of the function pointer in the class structure - * for this type. Used to invoke a class method generically. Pass 0 to - * not associate a class method slot with this signal. - * @accumulator: (nullable): the accumulator for this signal; may be %NULL. - * @accu_data: (nullable) (closure accumulator): user data for the @accumulator. - * @c_marshaller: (nullable): the function to translate arrays of parameter - * values to signal emissions into C language callback invocations or %NULL. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal - * without a return value. - * @n_params: the number of parameter types to follow. - * @...: a list of types, one for each parameter. - * - * Creates a new signal. (This is usually done in the class initializer.) - * - * A signal name consists of segments consisting of ASCII letters and - * digits, separated by either the `-` or `_` character. The first - * character of a signal name must be a letter. Names which violate these - * rules lead to undefined behaviour. These are the same rules as for property - * naming (see g_param_spec_internal()). - * - * When registering a signal and looking up a signal, either separator can - * be used, but they cannot be mixed. Using `-` is considerably more efficient. - * Using `_` is discouraged. - * - * If 0 is used for @class_offset subclasses cannot override the class handler - * in their class_init method by doing super_class->signal_handler = my_signal_handler. - * Instead they will have to use g_signal_override_class_handler(). - * - * If @c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as - * the marshaller for this signal. In some simple cases, g_signal_new() - * will use a more optimized c_marshaller and va_marshaller for the signal - * instead of g_cclosure_marshal_generic(). - * - * If @c_marshaller is non-%NULL, you need to also specify a va_marshaller - * using g_signal_set_va_marshaller() or the generic va_marshaller will - * be used. - * - * Returns: the signal id - */ - - -/** - * g_signal_new_class_handler: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to - * types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when - * the default handler is to be invoked. You should at least specify - * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_handler: (nullable): a #GCallback which acts as class implementation of - * this signal. Used to invoke a class method generically. Pass %NULL to - * not associate a class method with this signal. - * @accumulator: (nullable): the accumulator for this signal; may be %NULL. - * @accu_data: (nullable) (closure accumulator): user data for the @accumulator. - * @c_marshaller: (nullable): the function to translate arrays of parameter - * values to signal emissions into C language callback invocations or %NULL. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal - * without a return value. - * @n_params: the number of parameter types to follow. - * @...: a list of types, one for each parameter. - * - * Creates a new signal. (This is usually done in the class initializer.) - * - * This is a variant of g_signal_new() that takes a C callback instead - * of a class offset for the signal's class handler. This function - * doesn't need a function pointer exposed in the class structure of - * an object definition, instead the function pointer is passed - * directly and can be overridden by derived classes with - * g_signal_override_class_closure() or - * g_signal_override_class_handler()and chained to with - * g_signal_chain_from_overridden() or - * g_signal_chain_from_overridden_handler(). - * - * See g_signal_new() for information about signal names. - * - * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as - * the marshaller for this signal. - * - * Returns: the signal id - * Since: 2.18 - */ - - -/** - * g_signal_new_valist: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to - * types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when - * the default handler is to be invoked. You should at least specify - * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_closure: (nullable): The closure to invoke on signal emission; may be %NULL. - * @accumulator: (nullable): the accumulator for this signal; may be %NULL. - * @accu_data: (nullable) (closure accumulator): user data for the @accumulator. - * @c_marshaller: (nullable): the function to translate arrays of parameter - * values to signal emissions into C language callback invocations or %NULL. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal - * without a return value. - * @n_params: the number of parameter types in @args. - * @args: va_list of #GType, one for each parameter. - * - * Creates a new signal. (This is usually done in the class initializer.) - * - * See g_signal_new() for details on allowed signal names. - * - * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as - * the marshaller for this signal. - * - * Returns: the signal id - */ - - -/** - * g_signal_newv: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to - * types which are derived from this type - * @signal_flags: a combination of #GSignalFlags specifying detail of when - * the default handler is to be invoked. You should at least specify - * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST - * @class_closure: (nullable): The closure to invoke on signal emission; - * may be %NULL - * @accumulator: (nullable): the accumulator for this signal; may be %NULL - * @accu_data: (nullable) (closure accumulator): user data for the @accumulator - * @c_marshaller: (nullable): the function to translate arrays of - * parameter values to signal emissions into C language callback - * invocations or %NULL - * @return_type: the type of return value, or #G_TYPE_NONE for a signal - * without a return value - * @n_params: the length of @param_types - * @param_types: (array length=n_params) (nullable): an array of types, one for - * each parameter (may be %NULL if @n_params is zero) - * - * Creates a new signal. (This is usually done in the class initializer.) - * - * See g_signal_new() for details on allowed signal names. - * - * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as - * the marshaller for this signal. - * - * Returns: the signal id - */ - - -/** - * g_signal_override_class_closure: - * @signal_id: the signal id - * @instance_type: the instance type on which to override the class closure - * for the signal. - * @class_closure: the closure. - * - * Overrides the class closure (i.e. the default handler) for the given signal - * for emissions on instances of @instance_type. @instance_type must be derived - * from the type to which the signal belongs. - * - * See g_signal_chain_from_overridden() and - * g_signal_chain_from_overridden_handler() for how to chain up to the - * parent class closure from inside the overridden one. - */ - - -/** - * g_signal_override_class_handler: - * @signal_name: the name for the signal - * @instance_type: the instance type on which to override the class handler - * for the signal. - * @class_handler: the handler. - * - * Overrides the class closure (i.e. the default handler) for the - * given signal for emissions on instances of @instance_type with - * callback @class_handler. @instance_type must be derived from the - * type to which the signal belongs. - * - * See g_signal_chain_from_overridden() and - * g_signal_chain_from_overridden_handler() for how to chain up to the - * parent class closure from inside the overridden one. - * - * Since: 2.18 - */ - - -/** - * g_signal_parse_name: - * @detailed_signal: a string of the form "signal-name::detail". - * @itype: The interface/instance type that introduced "signal-name". - * @signal_id_p: (out): Location to store the signal id. - * @detail_p: (out): Location to store the detail quark. - * @force_detail_quark: %TRUE forces creation of a #GQuark for the detail. - * - * Internal function to parse a signal name into its @signal_id - * and @detail quark. - * - * Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. - */ - - -/** - * g_signal_query: - * @signal_id: The signal id of the signal to query information for. - * @query: (out caller-allocates) (not optional): A user provided structure that is - * filled in with constant values upon success. - * - * Queries the signal system for in-depth information about a - * specific signal. This function will fill in a user-provided - * structure to hold signal-specific information. If an invalid - * signal id is passed in, the @signal_id member of the #GSignalQuery - * is 0. All members filled into the #GSignalQuery structure should - * be considered constant and have to be left untouched. - */ - - -/** - * g_signal_remove_emission_hook: - * @signal_id: the id of the signal - * @hook_id: the id of the emission hook, as returned by - * g_signal_add_emission_hook() - * - * Deletes an emission hook. - */ - - -/** - * g_signal_set_va_marshaller: - * @signal_id: the signal id - * @instance_type: the instance type on which to set the marshaller. - * @va_marshaller: the marshaller to set. - * - * Change the #GSignalCVaMarshaller used for a given signal. This is a - * specialised form of the marshaller that can often be used for the - * common case of a single connected signal handler and avoids the - * overhead of #GValue. Its use is optional. - * - * Since: 2.32 - */ - - -/** - * g_signal_stop_emission: - * @instance: (type GObject.Object): the object whose signal handlers you wish to stop. - * @signal_id: the signal identifier, as returned by g_signal_lookup(). - * @detail: the detail which the signal was emitted with. - * - * Stops a signal's current emission. - * - * This will prevent the default method from running, if the signal was - * %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" - * flag). - * - * Prints a warning if used on a signal which isn't being emitted. - */ - - -/** - * g_signal_stop_emission_by_name: - * @instance: (type GObject.Object): the object whose signal handlers you wish to stop. - * @detailed_signal: a string of the form "signal-name::detail". - * - * Stops a signal's current emission. - * - * This is just like g_signal_stop_emission() except it will look up the - * signal id for you. - */ - - -/** - * g_signal_type_cclosure_new: - * @itype: the #GType identifier of an interface or classed type - * @struct_offset: the offset of the member function of @itype's class - * structure which is to be invoked by the new closure - * - * Creates a new closure which invokes the function found at the offset - * @struct_offset in the class structure of the interface or classed type - * identified by @itype. - * - * Returns: (transfer none): a floating reference to a new #GCClosure - */ - - -/** - * g_source_set_closure: - * @source: the source - * @closure: a #GClosure - * - * Set the callback for a source as a #GClosure. - * - * If the source is not one of the standard GLib types, the @closure_callback - * and @closure_marshal fields of the #GSourceFuncs structure must have been - * filled in with pointers to appropriate functions. - */ - - -/** - * g_source_set_dummy_callback: - * @source: the source - * - * Sets a dummy callback for @source. The callback will do nothing, and - * if the source expects a #gboolean return value, it will return %TRUE. - * (If the source expects any other type of return value, it will return - * a 0/%NULL value; whatever g_value_init() initializes a #GValue to for - * that type.) - * - * If the source is not one of the standard GLib types, the - * @closure_callback and @closure_marshal fields of the #GSourceFuncs - * structure must have been filled in with pointers to appropriate - * functions. - */ - - -/** - * g_strdup_value_contents: - * @value: #GValue which contents are to be described. - * - * Return a newly allocated string, which describes the contents of a - * #GValue. The main purpose of this function is to describe #GValue - * contents for debugging output, the way in which the contents are - * described may change between different GLib versions. - * - * Returns: Newly allocated string. - */ - - -/** - * g_type_add_class_cache_func: (skip) - * @cache_data: data to be passed to @cache_func - * @cache_func: a #GTypeClassCacheFunc - * - * Adds a #GTypeClassCacheFunc to be called before the reference count of a - * class goes from one to zero. This can be used to prevent premature class - * destruction. All installed #GTypeClassCacheFunc functions will be chained - * until one of them returns %TRUE. The functions have to check the class id - * passed in to figure whether they actually want to cache the class of this - * type, since all classes are routed through the same #GTypeClassCacheFunc - * chain. - */ - - -/** - * g_type_add_class_private: - * @class_type: GType of a classed type - * @private_size: size of private structure - * - * Registers a private class structure for a classed type; - * when the class is allocated, the private structures for - * the class and all of its parent types are allocated - * sequentially in the same memory block as the public - * structures, and are zero-filled. - * - * This function should be called in the - * type's get_type() function after the type is registered. - * The private structure can be retrieved using the - * G_TYPE_CLASS_GET_PRIVATE() macro. - * - * Since: 2.24 - */ - - -/** - * g_type_add_interface_check: (skip) - * @check_data: data to pass to @check_func - * @check_func: function to be called after each interface - * is initialized - * - * Adds a function to be called after an interface vtable is - * initialized for any class (i.e. after the @interface_init - * member of #GInterfaceInfo has been called). - * - * This function is useful when you want to check an invariant - * that depends on the interfaces of a class. For instance, the - * implementation of #GObject uses this facility to check that an - * object implements all of the properties that are defined on its - * interfaces. - * - * Since: 2.4 - */ - - -/** - * g_type_add_interface_dynamic: - * @instance_type: #GType value of an instantiatable type - * @interface_type: #GType value of an interface type - * @plugin: #GTypePlugin structure to retrieve the #GInterfaceInfo from - * - * Adds @interface_type to the dynamic @instance_type. The information - * contained in the #GTypePlugin structure pointed to by @plugin - * is used to manage the relationship. - */ - - -/** - * g_type_add_interface_static: - * @instance_type: #GType value of an instantiatable type - * @interface_type: #GType value of an interface type - * @info: #GInterfaceInfo structure for this - * (@instance_type, @interface_type) combination - * - * Adds @interface_type to the static @instance_type. - * The information contained in the #GInterfaceInfo structure - * pointed to by @info is used to manage the relationship. - */ - - -/** - * g_type_check_instance: - * @instance: a valid #GTypeInstance structure - * - * Private helper function to aid implementation of the - * G_TYPE_CHECK_INSTANCE() macro. - * - * Returns: %TRUE if @instance is valid, %FALSE otherwise - */ - - -/** - * g_type_children: - * @type: the parent type - * @n_children: (out) (optional): location to store the length of - * the returned array, or %NULL - * - * Return a newly allocated and 0-terminated array of type IDs, listing - * the child types of @type. - * - * Returns: (array length=n_children) (transfer full): Newly allocated - * and 0-terminated array of child types, free with g_free() - */ - - -/** - * g_type_class_add_private: - * @g_class: (type GObject.TypeClass): class structure for an instantiatable - * type - * @private_size: size of private structure - * - * Registers a private structure for an instantiatable type. - * - * When an object is allocated, the private structures for - * the type and all of its parent types are allocated - * sequentially in the same memory block as the public - * structures, and are zero-filled. - * - * Note that the accumulated size of the private structures of - * a type and all its parent types cannot exceed 64 KiB. - * - * This function should be called in the type's class_init() function. - * The private structure can be retrieved using the - * G_TYPE_INSTANCE_GET_PRIVATE() macro. - * - * The following example shows attaching a private structure - * MyObjectPrivate to an object MyObject defined in the standard - * GObject fashion in the type's class_init() function. - * - * Note the use of a structure member "priv" to avoid the overhead - * of repeatedly calling MY_OBJECT_GET_PRIVATE(). - * - * |[<!-- language="C" --> - * typedef struct _MyObject MyObject; - * typedef struct _MyObjectPrivate MyObjectPrivate; - * - * struct _MyObject { - * GObject parent; - * - * MyObjectPrivate *priv; - * }; - * - * struct _MyObjectPrivate { - * int some_field; - * }; - * - * static void - * my_object_class_init (MyObjectClass *klass) - * { - * g_type_class_add_private (klass, sizeof (MyObjectPrivate)); - * } - * - * static void - * my_object_init (MyObject *my_object) - * { - * my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object, - * MY_TYPE_OBJECT, - * MyObjectPrivate); - * // my_object->priv->some_field will be automatically initialised to 0 - * } - * - * static int - * my_object_get_some_field (MyObject *my_object) - * { - * MyObjectPrivate *priv; - * - * g_return_val_if_fail (MY_IS_OBJECT (my_object), 0); - * - * priv = my_object->priv; - * - * return priv->some_field; - * } - * ]| - * - * Since: 2.4 - * Deprecated: 2.58: Use the G_ADD_PRIVATE() macro with the `G_DEFINE_*` - * family of macros to add instance private data to a type - */ - - -/** - * g_type_class_get_instance_private_offset: (skip) - * @g_class: (type GObject.TypeClass): a #GTypeClass - * - * Gets the offset of the private data for instances of @g_class. - * - * This is how many bytes you should add to the instance pointer of a - * class in order to get the private data for the type represented by - * @g_class. - * - * You can only call this function after you have registered a private - * data area for @g_class using g_type_class_add_private(). - * - * Returns: the offset, in bytes - * Since: 2.38 - */ - - -/** - * g_type_class_peek: - * @type: type ID of a classed type - * - * This function is essentially the same as g_type_class_ref(), - * except that the classes reference count isn't incremented. - * As a consequence, this function may return %NULL if the class - * of the type passed in does not currently exist (hasn't been - * referenced before). - * - * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass - * structure for the given type ID or %NULL if the class does not - * currently exist - */ - - -/** - * g_type_class_peek_parent: - * @g_class: (type GObject.TypeClass): the #GTypeClass structure to - * retrieve the parent class for - * - * This is a convenience function often needed in class initializers. - * It returns the class structure of the immediate parent type of the - * class passed in. Since derived classes hold a reference count on - * their parent classes as long as they are instantiated, the returned - * class will always exist. - * - * This function is essentially equivalent to: - * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))) - * - * Returns: (type GObject.TypeClass) (transfer none): the parent class - * of @g_class - */ - - -/** - * g_type_class_peek_static: - * @type: type ID of a classed type - * - * A more efficient version of g_type_class_peek() which works only for - * static types. - * - * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass - * structure for the given type ID or %NULL if the class does not - * currently exist or is dynamically loaded - * Since: 2.4 - */ - - -/** - * g_type_class_ref: - * @type: type ID of a classed type - * - * Increments the reference count of the class structure belonging to - * @type. This function will demand-create the class if it doesn't - * exist already. - * - * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass - * structure for the given type ID - */ - - -/** - * g_type_class_unref: - * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref - * - * Decrements the reference count of the class structure being passed in. - * Once the last reference count of a class has been released, classes - * may be finalized by the type system, so further dereferencing of a - * class pointer after g_type_class_unref() are invalid. - */ - - -/** - * g_type_class_unref_uncached: (skip) - * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref - * - * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc - * implementations. It unreferences a class without consulting the chain - * of #GTypeClassCacheFuncs, avoiding the recursion which would occur - * otherwise. - */ - - -/** - * g_type_create_instance: (skip) - * @type: an instantiatable type to create an instance for - * - * Creates and initializes an instance of @type if @type is valid and - * can be instantiated. The type system only performs basic allocation - * and structure setups for instances: actual instance creation should - * happen through functions supplied by the type's fundamental type - * implementation. So use of g_type_create_instance() is reserved for - * implementers of fundamental types only. E.g. instances of the - * #GObject hierarchy should be created via g_object_new() and never - * directly through g_type_create_instance() which doesn't handle things - * like singleton objects or object construction. - * - * The extended members of the returned instance are guaranteed to be filled - * with zeros. - * - * Note: Do not use this function, unless you're implementing a - * fundamental type. Also language bindings should not use this - * function, but g_object_new() instead. - * - * Returns: an allocated and initialized instance, subject to further - * treatment by the fundamental type implementation - */ - - -/** - * g_type_default_interface_peek: - * @g_type: an interface type - * - * If the interface type @g_type is currently in use, returns its - * default interface vtable. - * - * Since: 2.4 - * Returns: (type GObject.TypeInterface) (transfer none): the default - * vtable for the interface, or %NULL if the type is not currently - * in use - */ - - -/** - * g_type_default_interface_ref: - * @g_type: an interface type - * - * Increments the reference count for the interface type @g_type, - * and returns the default interface vtable for the type. - * - * If the type is not currently in use, then the default vtable - * for the type will be created and initialized by calling - * the base interface init and default vtable init functions for - * the type (the @base_init and @class_init members of #GTypeInfo). - * Calling g_type_default_interface_ref() is useful when you - * want to make sure that signals and properties for an interface - * have been installed. - * - * Since: 2.4 - * Returns: (type GObject.TypeInterface) (transfer none): the default - * vtable for the interface; call g_type_default_interface_unref() - * when you are done using the interface. - */ - - -/** - * g_type_default_interface_unref: - * @g_iface: (type GObject.TypeInterface): the default vtable - * structure for an interface, as returned by g_type_default_interface_ref() - * - * Decrements the reference count for the type corresponding to the - * interface default vtable @g_iface. If the type is dynamic, then - * when no one is using the interface and all references have - * been released, the finalize function for the interface's default - * vtable (the @class_finalize member of #GTypeInfo) will be called. - * - * Since: 2.4 - */ - - -/** - * g_type_depth: - * @type: a #GType - * - * Returns the length of the ancestry of the passed in type. This - * includes the type itself, so that e.g. a fundamental type has depth 1. - * - * Returns: the depth of @type - */ - - -/** - * g_type_ensure: - * @type: a #GType - * - * Ensures that the indicated @type has been registered with the - * type system, and its _class_init() method has been run. - * - * In theory, simply calling the type's _get_type() method (or using - * the corresponding macro) is supposed take care of this. However, - * _get_type() methods are often marked %G_GNUC_CONST for performance - * reasons, even though this is technically incorrect (since - * %G_GNUC_CONST requires that the function not have side effects, - * which _get_type() methods do on the first call). As a result, if - * you write a bare call to a _get_type() macro, it may get optimized - * out by the compiler. Using g_type_ensure() guarantees that the - * type's _get_type() method is called. - * - * Since: 2.34 - */ - - -/** - * g_type_free_instance: - * @instance: an instance of a type - * - * Frees an instance of a type, returning it to the instance pool for - * the type, if there is one. - * - * Like g_type_create_instance(), this function is reserved for - * implementors of fundamental types. - */ - - -/** - * g_type_from_name: - * @name: type name to look up - * - * Look up the type ID from a given type name, returning 0 if no type - * has been registered under this name (this is the preferred method - * to find out by name whether a specific type has been registered - * yet). - * - * Returns: corresponding type ID or 0 - */ - - -/** - * g_type_fundamental: - * @type_id: valid type ID - * - * Internal function, used to extract the fundamental type ID portion. - * Use G_TYPE_FUNDAMENTAL() instead. - * - * Returns: fundamental type ID - */ - - -/** - * g_type_fundamental_next: - * - * Returns the next free fundamental type id which can be used to - * register a new fundamental type with g_type_register_fundamental(). - * The returned type ID represents the highest currently registered - * fundamental type identifier. - * - * Returns: the next available fundamental type ID to be registered, - * or 0 if the type system ran out of fundamental type IDs - */ - - -/** - * g_type_get_instance_count: - * @type: a #GType - * - * Returns the number of instances allocated of the particular type; - * this is only available if GLib is built with debugging support and - * the instance_count debug flag is set (by setting the GOBJECT_DEBUG - * variable to include instance-count). - * - * Returns: the number of instances allocated of the given type; - * if instance counts are not available, returns 0. - * Since: 2.44 - */ - - -/** - * g_type_get_plugin: - * @type: #GType to retrieve the plugin for - * - * Returns the #GTypePlugin structure for @type. - * - * Returns: (transfer none): the corresponding plugin - * if @type is a dynamic type, %NULL otherwise - */ - - -/** - * g_type_get_qdata: - * @type: a #GType - * @quark: a #GQuark id to identify the data - * - * Obtains data which has previously been attached to @type - * with g_type_set_qdata(). - * - * Note that this does not take subtyping into account; data - * attached to one type with g_type_set_qdata() cannot - * be retrieved from a subtype using g_type_get_qdata(). - * - * Returns: (transfer none): the data, or %NULL if no data was found - */ - - -/** - * g_type_get_type_registration_serial: - * - * Returns an opaque serial number that represents the state of the set - * of registered types. Any time a type is registered this serial changes, - * which means you can cache information based on type lookups (such as - * g_type_from_name()) and know if the cache is still valid at a later - * time by comparing the current serial with the one at the type lookup. - * - * Since: 2.36 - * Returns: An unsigned int, representing the state of type registrations - */ - - -/** - * g_type_init: - * - * This function used to initialise the type system. Since GLib 2.36, - * the type system is initialised automatically and this function does - * nothing. - * - * Deprecated: 2.36: the type system is now initialised automatically - */ - - -/** - * g_type_init_with_debug_flags: - * @debug_flags: bitwise combination of #GTypeDebugFlags values for - * debugging purposes - * - * This function used to initialise the type system with debugging - * flags. Since GLib 2.36, the type system is initialised automatically - * and this function does nothing. - * - * If you need to enable debugging features, use the GOBJECT_DEBUG - * environment variable. - * - * Deprecated: 2.36: the type system is now initialised automatically - */ - - -/** - * g_type_interface_add_prerequisite: - * @interface_type: #GType value of an interface type - * @prerequisite_type: #GType value of an interface or instantiatable type - * - * Adds @prerequisite_type to the list of prerequisites of @interface_type. - * This means that any type implementing @interface_type must also implement - * @prerequisite_type. Prerequisites can be thought of as an alternative to - * interface derivation (which GType doesn't support). An interface can have - * at most one instantiatable prerequisite type. - */ - - -/** - * g_type_interface_get_plugin: - * @instance_type: #GType of an instantiatable type - * @interface_type: #GType of an interface type - * - * Returns the #GTypePlugin structure for the dynamic interface - * @interface_type which has been added to @instance_type, or %NULL - * if @interface_type has not been added to @instance_type or does - * not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). - * - * Returns: (transfer none): the #GTypePlugin for the dynamic - * interface @interface_type of @instance_type - */ - - -/** - * g_type_interface_instantiatable_prerequisite: - * @interface_type: an interface type - * - * Returns the most specific instantiatable prerequisite of an - * interface type. If the interface type has no instantiatable - * prerequisite, %G_TYPE_INVALID is returned. - * - * See g_type_interface_add_prerequisite() for more information - * about prerequisites. - * - * Returns: the instantiatable prerequisite type or %G_TYPE_INVALID if none - * Since: 2.68 - */ - - -/** - * g_type_interface_peek: - * @instance_class: (type GObject.TypeClass): a #GTypeClass structure - * @iface_type: an interface ID which this class conforms to - * - * Returns the #GTypeInterface structure of an interface to which the - * passed in class conforms. - * - * Returns: (type GObject.TypeInterface) (transfer none): the #GTypeInterface - * structure of @iface_type if implemented by @instance_class, %NULL - * otherwise - */ - - -/** - * g_type_interface_peek_parent: - * @g_iface: (type GObject.TypeInterface): a #GTypeInterface structure - * - * Returns the corresponding #GTypeInterface structure of the parent type - * of the instance type to which @g_iface belongs. This is useful when - * deriving the implementation of an interface from the parent type and - * then possibly overriding some methods. - * - * Returns: (transfer none) (type GObject.TypeInterface): the - * corresponding #GTypeInterface structure of the parent type of the - * instance type to which @g_iface belongs, or %NULL if the parent - * type doesn't conform to the interface - */ - - -/** - * g_type_interface_prerequisites: - * @interface_type: an interface type - * @n_prerequisites: (out) (optional): location to return the number - * of prerequisites, or %NULL - * - * Returns the prerequisites of an interfaces type. - * - * Since: 2.2 - * Returns: (array length=n_prerequisites) (transfer full): a - * newly-allocated zero-terminated array of #GType containing - * the prerequisites of @interface_type - */ - - -/** - * g_type_interfaces: - * @type: the type to list interface types for - * @n_interfaces: (out) (optional): location to store the length of - * the returned array, or %NULL - * - * Return a newly allocated and 0-terminated array of type IDs, listing - * the interface types that @type conforms to. - * - * Returns: (array length=n_interfaces) (transfer full): Newly allocated - * and 0-terminated array of interface types, free with g_free() - */ - - -/** - * g_type_is_a: - * @type: type to check ancestry for - * @is_a_type: possible ancestor of @type or interface that @type - * could conform to - * - * If @is_a_type is a derivable type, check whether @type is a - * descendant of @is_a_type. If @is_a_type is an interface, check - * whether @type conforms to it. - * - * Returns: %TRUE if @type is a @is_a_type - */ - - -/** - * g_type_module_add_interface: - * @module: (nullable): a #GTypeModule - * @instance_type: type to which to add the interface. - * @interface_type: interface type to add - * @interface_info: type information structure - * - * Registers an additional interface for a type, whose interface lives - * in the given type plugin. If the interface was already registered - * for the type in this plugin, nothing will be done. - * - * As long as any instances of the type exist, the type plugin will - * not be unloaded. - * - * Since 2.56 if @module is %NULL this will call g_type_add_interface_static() - * instead. This can be used when making a static build of the module. - */ - - -/** - * g_type_module_register_enum: - * @module: (nullable): a #GTypeModule - * @name: name for the type - * @const_static_values: an array of #GEnumValue structs for the - * possible enumeration values. The array is - * terminated by a struct with all members being - * 0. - * - * Looks up or registers an enumeration that is implemented with a particular - * type plugin. If a type with name @type_name was previously registered, - * the #GType identifier for the type is returned, otherwise the type - * is newly registered, and the resulting #GType identifier returned. - * - * As long as any instances of the type exist, the type plugin will - * not be unloaded. - * - * Since 2.56 if @module is %NULL this will call g_type_register_static() - * instead. This can be used when making a static build of the module. - * - * Since: 2.6 - * Returns: the new or existing type ID - */ - - -/** - * g_type_module_register_flags: - * @module: (nullable): a #GTypeModule - * @name: name for the type - * @const_static_values: an array of #GFlagsValue structs for the - * possible flags values. The array is - * terminated by a struct with all members being - * 0. - * - * Looks up or registers a flags type that is implemented with a particular - * type plugin. If a type with name @type_name was previously registered, - * the #GType identifier for the type is returned, otherwise the type - * is newly registered, and the resulting #GType identifier returned. - * - * As long as any instances of the type exist, the type plugin will - * not be unloaded. - * - * Since 2.56 if @module is %NULL this will call g_type_register_static() - * instead. This can be used when making a static build of the module. - * - * Since: 2.6 - * Returns: the new or existing type ID - */ - - -/** - * g_type_module_register_type: - * @module: (nullable): a #GTypeModule - * @parent_type: the type for the parent class - * @type_name: name for the type - * @type_info: type information structure - * @flags: flags field providing details about the type - * - * Looks up or registers a type that is implemented with a particular - * type plugin. If a type with name @type_name was previously registered, - * the #GType identifier for the type is returned, otherwise the type - * is newly registered, and the resulting #GType identifier returned. - * - * When reregistering a type (typically because a module is unloaded - * then reloaded, and reinitialized), @module and @parent_type must - * be the same as they were previously. - * - * As long as any instances of the type exist, the type plugin will - * not be unloaded. - * - * Since 2.56 if @module is %NULL this will call g_type_register_static() - * instead. This can be used when making a static build of the module. - * - * Returns: the new or existing type ID - */ - - -/** - * g_type_module_set_name: - * @module: a #GTypeModule. - * @name: a human-readable name to use in error messages. - * - * Sets the name for a #GTypeModule - */ - - -/** - * g_type_module_unuse: - * @module: a #GTypeModule - * - * Decreases the use count of a #GTypeModule by one. If the - * result is zero, the module will be unloaded. (However, the - * #GTypeModule will not be freed, and types associated with the - * #GTypeModule are not unregistered. Once a #GTypeModule is - * initialized, it must exist forever.) - */ - - -/** - * g_type_module_use: - * @module: a #GTypeModule - * - * Increases the use count of a #GTypeModule by one. If the - * use count was zero before, the plugin will be loaded. - * If loading the plugin fails, the use count is reset to - * its prior value. - * - * Returns: %FALSE if the plugin needed to be loaded and - * loading the plugin failed. - */ - - -/** - * g_type_name: - * @type: type to return name for - * - * Get the unique name that is assigned to a type ID. Note that this - * function (like all other GType API) cannot cope with invalid type - * IDs. %G_TYPE_INVALID may be passed to this function, as may be any - * other validly registered type ID, but randomized type IDs should - * not be passed in and will most likely lead to a crash. - * - * Returns: static type name or %NULL - */ - - -/** - * g_type_next_base: - * @leaf_type: descendant of @root_type and the type to be returned - * @root_type: immediate parent of the returned type - * - * Given a @leaf_type and a @root_type which is contained in its - * ancestry, return the type that @root_type is the immediate parent - * of. In other words, this function determines the type that is - * derived directly from @root_type which is also a base class of - * @leaf_type. Given a root type and a leaf type, this function can - * be used to determine the types and order in which the leaf type is - * descended from the root type. - * - * Returns: immediate child of @root_type and ancestor of @leaf_type - */ - - -/** - * g_type_parent: - * @type: the derived type - * - * Return the direct parent type of the passed in type. If the passed - * in type has no parent, i.e. is a fundamental type, 0 is returned. - * - * Returns: the parent type - */ - - -/** - * g_type_plugin_complete_interface_info: - * @plugin: the #GTypePlugin - * @instance_type: the #GType of an instantiatable type to which the interface - * is added - * @interface_type: the #GType of the interface whose info is completed - * @info: the #GInterfaceInfo to fill in - * - * Calls the @complete_interface_info function from the - * #GTypePluginClass of @plugin. There should be no need to use this - * function outside of the GObject type system itself. - */ - - -/** - * g_type_plugin_complete_type_info: - * @plugin: a #GTypePlugin - * @g_type: the #GType whose info is completed - * @info: the #GTypeInfo struct to fill in - * @value_table: the #GTypeValueTable to fill in - * - * Calls the @complete_type_info function from the #GTypePluginClass of @plugin. - * There should be no need to use this function outside of the GObject - * type system itself. - */ - - -/** - * g_type_plugin_unuse: - * @plugin: a #GTypePlugin - * - * Calls the @unuse_plugin function from the #GTypePluginClass of - * @plugin. There should be no need to use this function outside of - * the GObject type system itself. - */ - - -/** - * g_type_plugin_use: - * @plugin: a #GTypePlugin - * - * Calls the @use_plugin function from the #GTypePluginClass of - * @plugin. There should be no need to use this function outside of - * the GObject type system itself. - */ - - -/** - * g_type_qname: - * @type: type to return quark of type name for - * - * Get the corresponding quark of the type IDs name. - * - * Returns: the type names quark or 0 - */ - - -/** - * g_type_query: - * @type: #GType of a static, classed type - * @query: (out caller-allocates): a user provided structure that is - * filled in with constant values upon success - * - * Queries the type system for information about a specific type. - * This function will fill in a user-provided structure to hold - * type-specific information. If an invalid #GType is passed in, the - * @type member of the #GTypeQuery is 0. All members filled into the - * #GTypeQuery structure should be considered constant and have to be - * left untouched. - */ - - -/** - * g_type_register_dynamic: - * @parent_type: type from which this type will be derived - * @type_name: 0-terminated string used as the name of the new type - * @plugin: #GTypePlugin structure to retrieve the #GTypeInfo from - * @flags: bitwise combination of #GTypeFlags values - * - * Registers @type_name as the name of a new dynamic type derived from - * @parent_type. The type system uses the information contained in the - * #GTypePlugin structure pointed to by @plugin to manage the type and its - * instances (if not abstract). The value of @flags determines the nature - * (e.g. abstract or not) of the type. - * - * Returns: the new type identifier or #G_TYPE_INVALID if registration failed - */ - - -/** - * g_type_register_fundamental: - * @type_id: a predefined type identifier - * @type_name: 0-terminated string used as the name of the new type - * @info: #GTypeInfo structure for this type - * @finfo: #GTypeFundamentalInfo structure for this type - * @flags: bitwise combination of #GTypeFlags values - * - * Registers @type_id as the predefined identifier and @type_name as the - * name of a fundamental type. If @type_id is already registered, or a - * type named @type_name is already registered, the behaviour is undefined. - * The type system uses the information contained in the #GTypeInfo structure - * pointed to by @info and the #GTypeFundamentalInfo structure pointed to by - * @finfo to manage the type and its instances. The value of @flags determines - * additional characteristics of the fundamental type. - * - * Returns: the predefined type identifier - */ - - -/** - * g_type_register_static: - * @parent_type: type from which this type will be derived - * @type_name: 0-terminated string used as the name of the new type - * @info: #GTypeInfo structure for this type - * @flags: bitwise combination of #GTypeFlags values - * - * Registers @type_name as the name of a new static type derived from - * @parent_type. The type system uses the information contained in the - * #GTypeInfo structure pointed to by @info to manage the type and its - * instances (if not abstract). The value of @flags determines the nature - * (e.g. abstract or not) of the type. - * - * Returns: the new type identifier - */ - - -/** - * g_type_register_static_simple: (skip) - * @parent_type: type from which this type will be derived - * @type_name: 0-terminated string used as the name of the new type - * @class_size: size of the class structure (see #GTypeInfo) - * @class_init: location of the class initialization function (see #GTypeInfo) - * @instance_size: size of the instance structure (see #GTypeInfo) - * @instance_init: location of the instance initialization function (see #GTypeInfo) - * @flags: bitwise combination of #GTypeFlags values - * - * Registers @type_name as the name of a new static type derived from - * @parent_type. The value of @flags determines the nature (e.g. - * abstract or not) of the type. It works by filling a #GTypeInfo - * struct and calling g_type_register_static(). - * - * Since: 2.12 - * Returns: the new type identifier - */ - - -/** - * g_type_remove_class_cache_func: (skip) - * @cache_data: data that was given when adding @cache_func - * @cache_func: a #GTypeClassCacheFunc - * - * Removes a previously installed #GTypeClassCacheFunc. The cache - * maintained by @cache_func has to be empty when calling - * g_type_remove_class_cache_func() to avoid leaks. - */ - - -/** - * g_type_remove_interface_check: (skip) - * @check_data: callback data passed to g_type_add_interface_check() - * @check_func: callback function passed to g_type_add_interface_check() - * - * Removes an interface check function added with - * g_type_add_interface_check(). - * - * Since: 2.4 - */ - - -/** - * g_type_set_qdata: - * @type: a #GType - * @quark: a #GQuark id to identify the data - * @data: the data - * - * Attaches arbitrary data to a type. - */ - - -/** - * g_type_value_table_peek: (skip) - * @type: a #GType - * - * Returns the location of the #GTypeValueTable associated with @type. - * - * Note that this function should only be used from source code - * that implements or has internal knowledge of the implementation of - * @type. - * - * Returns: location of the #GTypeValueTable associated with @type or - * %NULL if there is no #GTypeValueTable associated with @type - */ - - -/** - * g_value_array_append: - * @value_array: #GValueArray to add an element to - * @value: (nullable): #GValue to copy into #GValueArray, or %NULL - * - * Insert a copy of @value as last element of @value_array. If @value is - * %NULL, an uninitialized value is appended. - * - * Returns: (transfer none): the #GValueArray passed in as @value_array - * Deprecated: 2.32: Use #GArray and g_array_append_val() instead. - */ - - -/** - * g_value_array_copy: - * @value_array: #GValueArray to copy - * - * Construct an exact copy of a #GValueArray by duplicating all its - * contents. - * - * Returns: (transfer full): Newly allocated copy of #GValueArray - * Deprecated: 2.32: Use #GArray and g_array_ref() instead. - */ - - -/** - * g_value_array_free: (skip) - * @value_array: #GValueArray to free - * - * Free a #GValueArray including its contents. - * - * Deprecated: 2.32: Use #GArray and g_array_unref() instead. - */ - - -/** - * g_value_array_get_nth: - * @value_array: #GValueArray to get a value from - * @index_: index of the value of interest - * - * Return a pointer to the value at @index_ containd in @value_array. - * - * Returns: (transfer none): pointer to a value at @index_ in @value_array - * Deprecated: 2.32: Use g_array_index() instead. - */ - - -/** - * g_value_array_insert: - * @value_array: #GValueArray to add an element to - * @index_: insertion position, must be <= value_array->;n_values - * @value: (nullable): #GValue to copy into #GValueArray, or %NULL - * - * Insert a copy of @value at specified position into @value_array. If @value - * is %NULL, an uninitialized value is inserted. - * - * Returns: (transfer none): the #GValueArray passed in as @value_array - * Deprecated: 2.32: Use #GArray and g_array_insert_val() instead. - */ - - -/** - * g_value_array_new: - * @n_prealloced: number of values to preallocate space for - * - * Allocate and initialize a new #GValueArray, optionally preserve space - * for @n_prealloced elements. New arrays always contain 0 elements, - * regardless of the value of @n_prealloced. - * - * Returns: a newly allocated #GValueArray with 0 values - * Deprecated: 2.32: Use #GArray and g_array_sized_new() instead. - */ - - -/** - * g_value_array_prepend: - * @value_array: #GValueArray to add an element to - * @value: (nullable): #GValue to copy into #GValueArray, or %NULL - * - * Insert a copy of @value as first element of @value_array. If @value is - * %NULL, an uninitialized value is prepended. - * - * Returns: (transfer none): the #GValueArray passed in as @value_array - * Deprecated: 2.32: Use #GArray and g_array_prepend_val() instead. - */ - - -/** - * g_value_array_remove: - * @value_array: #GValueArray to remove an element from - * @index_: position of value to remove, which must be less than - * @value_array->n_values - * - * Remove the value at position @index_ from @value_array. - * - * Returns: (transfer none): the #GValueArray passed in as @value_array - * Deprecated: 2.32: Use #GArray and g_array_remove_index() instead. - */ - - -/** - * g_value_array_sort: - * @value_array: #GValueArray to sort - * @compare_func: (scope call): function to compare elements - * - * Sort @value_array using @compare_func to compare the elements according to - * the semantics of #GCompareFunc. - * - * The current implementation uses the same sorting algorithm as standard - * C qsort() function. - * - * Returns: (transfer none): the #GValueArray passed in as @value_array - * Deprecated: 2.32: Use #GArray and g_array_sort(). - */ - - -/** - * g_value_array_sort_with_data: (rename-to g_value_array_sort) - * @value_array: #GValueArray to sort - * @compare_func: (scope call): function to compare elements - * @user_data: (closure): extra data argument provided for @compare_func - * - * Sort @value_array using @compare_func to compare the elements according - * to the semantics of #GCompareDataFunc. - * - * The current implementation uses the same sorting algorithm as standard - * C qsort() function. - * - * Returns: (transfer none): the #GValueArray passed in as @value_array - * Deprecated: 2.32: Use #GArray and g_array_sort_with_data(). - */ - - -/** - * g_value_copy: - * @src_value: An initialized #GValue structure. - * @dest_value: An initialized #GValue structure of the same type as @src_value. - * - * Copies the value of @src_value into @dest_value. - */ - - -/** - * g_value_dup_boxed: (skip) - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * - * Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, - * the boxed value is duplicated and needs to be later freed with - * g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), - * return_value); - * - * Returns: boxed contents of @value - */ - - -/** - * g_value_dup_object: - * @value: a valid #GValue whose type is derived from %G_TYPE_OBJECT - * - * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing - * its reference count. If the contents of the #GValue are %NULL, then - * %NULL will be returned. - * - * Returns: (type GObject.Object) (transfer full): object content of @value, - * should be unreferenced when no longer needed. - */ - - -/** - * g_value_dup_param: (skip) - * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM - * - * Get the contents of a %G_TYPE_PARAM #GValue, increasing its - * reference count. - * - * Returns: (transfer full): #GParamSpec content of @value, should be - * unreferenced when no longer needed. - */ - - -/** - * g_value_dup_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * - * Get a copy the contents of a %G_TYPE_STRING #GValue. - * - * Returns: a newly allocated copy of the string content of @value - */ - - -/** - * g_value_dup_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT - * - * Get the contents of a variant #GValue, increasing its refcount. The returned - * #GVariant is never floating. - * - * Returns: (transfer full) (nullable): variant contents of @value (may be %NULL); - * should be unreffed using g_variant_unref() when no longer needed - * Since: 2.26 - */ - - -/** - * g_value_fits_pointer: - * @value: An initialized #GValue structure. - * - * Determines if @value will fit inside the size of a pointer value. - * This is an internal function introduced mainly for C marshallers. - * - * Returns: %TRUE if @value will fit inside a pointer value. - */ - - -/** - * g_value_get_boolean: - * @value: a valid #GValue of type %G_TYPE_BOOLEAN - * - * Get the contents of a %G_TYPE_BOOLEAN #GValue. - * - * Returns: boolean contents of @value - */ - - -/** - * g_value_get_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * - * Get the contents of a %G_TYPE_BOXED derived #GValue. - * - * Returns: (transfer none): boxed contents of @value - */ - - -/** - * g_value_get_char: - * @value: a valid #GValue of type %G_TYPE_CHAR - * - * Do not use this function; it is broken on platforms where the %char - * type is unsigned, such as ARM and PowerPC. See g_value_get_schar(). - * - * Get the contents of a %G_TYPE_CHAR #GValue. - * - * Returns: character contents of @value - * Deprecated: 2.32: This function's return type is broken, see g_value_get_schar() - */ - - -/** - * g_value_get_double: - * @value: a valid #GValue of type %G_TYPE_DOUBLE - * - * Get the contents of a %G_TYPE_DOUBLE #GValue. - * - * Returns: double contents of @value - */ - - -/** - * g_value_get_enum: - * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM - * - * Get the contents of a %G_TYPE_ENUM #GValue. - * - * Returns: enum contents of @value - */ - - -/** - * g_value_get_flags: - * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS - * - * Get the contents of a %G_TYPE_FLAGS #GValue. - * - * Returns: flags contents of @value - */ - - -/** - * g_value_get_float: - * @value: a valid #GValue of type %G_TYPE_FLOAT - * - * Get the contents of a %G_TYPE_FLOAT #GValue. - * - * Returns: float contents of @value - */ - - -/** - * g_value_get_gtype: - * @value: a valid #GValue of type %G_TYPE_GTYPE - * - * Get the contents of a %G_TYPE_GTYPE #GValue. - * - * Since: 2.12 - * Returns: the #GType stored in @value - */ - - -/** - * g_value_get_int: - * @value: a valid #GValue of type %G_TYPE_INT - * - * Get the contents of a %G_TYPE_INT #GValue. - * - * Returns: integer contents of @value - */ - - -/** - * g_value_get_int64: - * @value: a valid #GValue of type %G_TYPE_INT64 - * - * Get the contents of a %G_TYPE_INT64 #GValue. - * - * Returns: 64bit integer contents of @value - */ - - -/** - * g_value_get_long: - * @value: a valid #GValue of type %G_TYPE_LONG - * - * Get the contents of a %G_TYPE_LONG #GValue. - * - * Returns: long integer contents of @value - */ - - -/** - * g_value_get_object: - * @value: a valid #GValue of %G_TYPE_OBJECT derived type - * - * Get the contents of a %G_TYPE_OBJECT derived #GValue. - * - * Returns: (type GObject.Object) (transfer none): object contents of @value - */ - - -/** - * g_value_get_param: - * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM - * - * Get the contents of a %G_TYPE_PARAM #GValue. - * - * Returns: (transfer none): #GParamSpec content of @value - */ - - -/** - * g_value_get_pointer: - * @value: a valid #GValue of %G_TYPE_POINTER - * - * Get the contents of a pointer #GValue. - * - * Returns: (transfer none): pointer contents of @value - */ - - -/** - * g_value_get_schar: - * @value: a valid #GValue of type %G_TYPE_CHAR - * - * Get the contents of a %G_TYPE_CHAR #GValue. - * - * Returns: signed 8 bit integer contents of @value - * Since: 2.32 - */ - - -/** - * g_value_get_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * - * Get the contents of a %G_TYPE_STRING #GValue. - * - * Returns: string content of @value - */ - - -/** - * g_value_get_uchar: - * @value: a valid #GValue of type %G_TYPE_UCHAR - * - * Get the contents of a %G_TYPE_UCHAR #GValue. - * - * Returns: unsigned character contents of @value - */ - - -/** - * g_value_get_uint: - * @value: a valid #GValue of type %G_TYPE_UINT - * - * Get the contents of a %G_TYPE_UINT #GValue. - * - * Returns: unsigned integer contents of @value - */ - - -/** - * g_value_get_uint64: - * @value: a valid #GValue of type %G_TYPE_UINT64 - * - * Get the contents of a %G_TYPE_UINT64 #GValue. - * - * Returns: unsigned 64bit integer contents of @value - */ - - -/** - * g_value_get_ulong: - * @value: a valid #GValue of type %G_TYPE_ULONG - * - * Get the contents of a %G_TYPE_ULONG #GValue. - * - * Returns: unsigned long integer contents of @value - */ - - -/** - * g_value_get_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT - * - * Get the contents of a variant #GValue. - * - * Returns: (transfer none) (nullable): variant contents of @value (may be %NULL) - * Since: 2.26 - */ - - -/** - * g_value_init: - * @value: A zero-filled (uninitialized) #GValue structure. - * @g_type: Type the #GValue should hold values of. - * - * Initializes @value with the default value of @type. - * - * Returns: (transfer none): the #GValue structure that has been passed in - */ - - -/** - * g_value_init_from_instance: - * @value: An uninitialized #GValue structure. - * @instance: (type GObject.TypeInstance): the instance - * - * Initializes and sets @value from an instantiatable type via the - * value_table's collect_value() function. - * - * Note: The @value will be initialised with the exact type of - * @instance. If you wish to set the @value's type to a different GType - * (such as a parent class GType), you need to manually call - * g_value_init() and g_value_set_instance(). - * - * Since: 2.42 - */ - - -/** - * g_value_peek_pointer: - * @value: An initialized #GValue structure - * - * Returns the value contents as pointer. This function asserts that - * g_value_fits_pointer() returned %TRUE for the passed in value. - * This is an internal function introduced mainly for C marshallers. - * - * Returns: (transfer none): the value contents as pointer - */ - - -/** - * g_value_register_transform_func: (skip) - * @src_type: Source type. - * @dest_type: Target type. - * @transform_func: a function which transforms values of type @src_type - * into value of type @dest_type - * - * Registers a value transformation function for use in g_value_transform(). - * A previously registered transformation function for @src_type and @dest_type - * will be replaced. - */ - - -/** - * g_value_reset: - * @value: An initialized #GValue structure. - * - * Clears the current value in @value and resets it to the default value - * (as if the value had just been initialized). - * - * Returns: the #GValue structure that has been passed in - */ - - -/** - * g_value_set_boolean: - * @value: a valid #GValue of type %G_TYPE_BOOLEAN - * @v_boolean: boolean value to be set - * - * Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. - */ - - -/** - * g_value_set_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: (nullable): boxed value to be set - * - * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. - */ - - -/** - * g_value_set_boxed_take_ownership: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: (nullable): duplicated unowned boxed value to be set - * - * This is an internal function introduced mainly for C marshallers. - * - * Deprecated: 2.4: Use g_value_take_boxed() instead. - */ - - -/** - * g_value_set_char: - * @value: a valid #GValue of type %G_TYPE_CHAR - * @v_char: character value to be set - * - * Set the contents of a %G_TYPE_CHAR #GValue to @v_char. - * - * Deprecated: 2.32: This function's input type is broken, see g_value_set_schar() - */ - - -/** - * g_value_set_double: - * @value: a valid #GValue of type %G_TYPE_DOUBLE - * @v_double: double value to be set - * - * Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. - */ - - -/** - * g_value_set_enum: - * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM - * @v_enum: enum value to be set - * - * Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. - */ - - -/** - * g_value_set_flags: - * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS - * @v_flags: flags value to be set - * - * Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. - */ - - -/** - * g_value_set_float: - * @value: a valid #GValue of type %G_TYPE_FLOAT - * @v_float: float value to be set - * - * Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. - */ - - -/** - * g_value_set_gtype: - * @value: a valid #GValue of type %G_TYPE_GTYPE - * @v_gtype: #GType to be set - * - * Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. - * - * Since: 2.12 - */ - - -/** - * g_value_set_instance: - * @value: An initialized #GValue structure. - * @instance: (nullable): the instance - * - * Sets @value from an instantiatable type via the - * value_table's collect_value() function. - */ - - -/** - * g_value_set_int: - * @value: a valid #GValue of type %G_TYPE_INT - * @v_int: integer value to be set - * - * Set the contents of a %G_TYPE_INT #GValue to @v_int. - */ - - -/** - * g_value_set_int64: - * @value: a valid #GValue of type %G_TYPE_INT64 - * @v_int64: 64bit integer value to be set - * - * Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. - */ - - -/** - * g_value_set_interned_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: (nullable): static string to be set - * - * Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is - * assumed to be static and interned (canonical, for example from - * g_intern_string()), and is thus not duplicated when setting the #GValue. - * - * Since: 2.66 - */ - - -/** - * g_value_set_long: - * @value: a valid #GValue of type %G_TYPE_LONG - * @v_long: long integer value to be set - * - * Set the contents of a %G_TYPE_LONG #GValue to @v_long. - */ - - -/** - * g_value_set_object: - * @value: a valid #GValue of %G_TYPE_OBJECT derived type - * @v_object: (type GObject.Object) (nullable): object value to be set - * - * Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. - * - * g_value_set_object() increases the reference count of @v_object - * (the #GValue holds a reference to @v_object). If you do not wish - * to increase the reference count of the object (i.e. you wish to - * pass your current reference to the #GValue because you no longer - * need it), use g_value_take_object() instead. - * - * It is important that your #GValue holds a reference to @v_object (either its - * own, or one it has taken) to ensure that the object won't be destroyed while - * the #GValue still exists). - */ - - -/** - * g_value_set_object_take_ownership: (skip) - * @value: a valid #GValue of %G_TYPE_OBJECT derived type - * @v_object: (nullable): object value to be set - * - * This is an internal function introduced mainly for C marshallers. - * - * Deprecated: 2.4: Use g_value_take_object() instead. - */ - - -/** - * g_value_set_param: - * @value: a valid #GValue of type %G_TYPE_PARAM - * @param: (nullable): the #GParamSpec to be set - * - * Set the contents of a %G_TYPE_PARAM #GValue to @param. - */ - - -/** - * g_value_set_param_take_ownership: (skip) - * @value: a valid #GValue of type %G_TYPE_PARAM - * @param: (nullable): the #GParamSpec to be set - * - * This is an internal function introduced mainly for C marshallers. - * - * Deprecated: 2.4: Use g_value_take_param() instead. - */ - - -/** - * g_value_set_pointer: - * @value: a valid #GValue of %G_TYPE_POINTER - * @v_pointer: pointer value to be set - * - * Set the contents of a pointer #GValue to @v_pointer. - */ - - -/** - * g_value_set_schar: - * @value: a valid #GValue of type %G_TYPE_CHAR - * @v_char: signed 8 bit integer to be set - * - * Set the contents of a %G_TYPE_CHAR #GValue to @v_char. - * - * Since: 2.32 - */ - - -/** - * g_value_set_static_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: (nullable): static boxed value to be set - * - * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. - * - * The boxed value is assumed to be static, and is thus not duplicated - * when setting the #GValue. - */ - - -/** - * g_value_set_static_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: (nullable): static string to be set - * - * Set the contents of a %G_TYPE_STRING #GValue to @v_string. - * The string is assumed to be static, and is thus not duplicated - * when setting the #GValue. - * - * If the the string is a canonical string, using g_value_set_interned_string() - * is more appropriate. - */ - - -/** - * g_value_set_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: (nullable): caller-owned string to be duplicated for the #GValue - * - * Set the contents of a %G_TYPE_STRING #GValue to a copy of @v_string. - */ - - -/** - * g_value_set_string_take_ownership: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: (nullable): duplicated unowned string to be set - * - * This is an internal function introduced mainly for C marshallers. - * - * Deprecated: 2.4: Use g_value_take_string() instead. - */ - - -/** - * g_value_set_uchar: - * @value: a valid #GValue of type %G_TYPE_UCHAR - * @v_uchar: unsigned character value to be set - * - * Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. - */ - - -/** - * g_value_set_uint: - * @value: a valid #GValue of type %G_TYPE_UINT - * @v_uint: unsigned integer value to be set - * - * Set the contents of a %G_TYPE_UINT #GValue to @v_uint. - */ - - -/** - * g_value_set_uint64: - * @value: a valid #GValue of type %G_TYPE_UINT64 - * @v_uint64: unsigned 64bit integer value to be set - * - * Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. - */ - - -/** - * g_value_set_ulong: - * @value: a valid #GValue of type %G_TYPE_ULONG - * @v_ulong: unsigned long integer value to be set - * - * Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. - */ - - -/** - * g_value_set_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT - * @variant: (nullable): a #GVariant, or %NULL - * - * Set the contents of a variant #GValue to @variant. - * If the variant is floating, it is consumed. - * - * Since: 2.26 - */ - - -/** - * g_value_take_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: (nullable): duplicated unowned boxed value to be set - * - * Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed - * and takes over the ownership of the caller’s reference to @v_boxed; - * the caller doesn’t have to unref it any more. - * - * Since: 2.4 - */ - - -/** - * g_value_take_object: (skip) - * @value: a valid #GValue of %G_TYPE_OBJECT derived type - * @v_object: (nullable): object value to be set - * - * Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object - * and takes over the ownership of the caller’s reference to @v_object; - * the caller doesn’t have to unref it any more (i.e. the reference - * count of the object is not increased). - * - * If you want the #GValue to hold its own reference to @v_object, use - * g_value_set_object() instead. - * - * Since: 2.4 - */ - - -/** - * g_value_take_param: (skip) - * @value: a valid #GValue of type %G_TYPE_PARAM - * @param: (nullable): the #GParamSpec to be set - * - * Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes - * over the ownership of the caller’s reference to @param; the caller - * doesn’t have to unref it any more. - * - * Since: 2.4 - */ - - -/** - * g_value_take_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: (nullable): string to take ownership of - * - * Sets the contents of a %G_TYPE_STRING #GValue to @v_string. - * - * Since: 2.4 - */ - - -/** - * g_value_take_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT - * @variant: (nullable) (transfer full): a #GVariant, or %NULL - * - * Set the contents of a variant #GValue to @variant, and takes over - * the ownership of the caller's reference to @variant; - * the caller doesn't have to unref it any more (i.e. the reference - * count of the variant is not increased). - * - * If @variant was floating then its floating reference is converted to - * a hard reference. - * - * If you want the #GValue to hold its own reference to @variant, use - * g_value_set_variant() instead. - * - * This is an internal function introduced mainly for C marshallers. - * - * Since: 2.26 - */ - - -/** - * g_value_transform: - * @src_value: Source value. - * @dest_value: Target value. - * - * Tries to cast the contents of @src_value into a type appropriate - * to store in @dest_value, e.g. to transform a %G_TYPE_INT value - * into a %G_TYPE_FLOAT value. Performing transformations between - * value types might incur precision lossage. Especially - * transformations into strings might reveal seemingly arbitrary - * results and shouldn't be relied upon for production code (such - * as rcfile value or object property serialization). - * - * Returns: Whether a transformation rule was found and could be applied. - * Upon failing transformations, @dest_value is left untouched. - */ - - -/** - * g_value_type_compatible: - * @src_type: source type to be copied. - * @dest_type: destination type for copying. - * - * Returns whether a #GValue of type @src_type can be copied into - * a #GValue of type @dest_type. - * - * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type. - */ - - -/** - * g_value_type_transformable: - * @src_type: Source type. - * @dest_type: Target type. - * - * Check whether g_value_transform() is able to transform values - * of type @src_type into values of type @dest_type. Note that for - * the types to be transformable, they must be compatible or a - * transformation function must be registered. - * - * Returns: %TRUE if the transformation is possible, %FALSE otherwise. - */ - - -/** - * g_value_unset: - * @value: An initialized #GValue structure. - * - * Clears the current value in @value (if any) and "unsets" the type, - * this releases all resources associated with this GValue. An unset - * value is the same as an uninitialized (zero-filled) #GValue - * structure. - */ - - -/** - * g_weak_ref_clear: (skip) - * @weak_ref: (inout): location of a weak reference, which - * may be empty - * - * Frees resources associated with a non-statically-allocated #GWeakRef. - * After this call, the #GWeakRef is left in an undefined state. - * - * You should only call this on a #GWeakRef that previously had - * g_weak_ref_init() called on it. - * - * Since: 2.32 - */ - - -/** - * g_weak_ref_get: (skip) - * @weak_ref: (inout): location of a weak reference to a #GObject - * - * If @weak_ref is not empty, atomically acquire a strong - * reference to the object it points to, and return that reference. - * - * This function is needed because of the potential race between taking - * the pointer value and g_object_ref() on it, if the object was losing - * its last reference at the same time in a different thread. - * - * The caller should release the resulting reference in the usual way, - * by using g_object_unref(). - * - * Returns: (transfer full) (type GObject.Object): the object pointed to - * by @weak_ref, or %NULL if it was empty - * Since: 2.32 - */ - - -/** - * g_weak_ref_init: (skip) - * @weak_ref: (inout): uninitialized or empty location for a weak - * reference - * @object: (type GObject.Object) (nullable): a #GObject or %NULL - * - * Initialise a non-statically-allocated #GWeakRef. - * - * This function also calls g_weak_ref_set() with @object on the - * freshly-initialised weak reference. - * - * This function should always be matched with a call to - * g_weak_ref_clear(). It is not necessary to use this function for a - * #GWeakRef in static storage because it will already be - * properly initialised. Just use g_weak_ref_set() directly. - * - * Since: 2.32 - */ - - -/** - * g_weak_ref_set: (skip) - * @weak_ref: location for a weak reference - * @object: (type GObject.Object) (nullable): a #GObject or %NULL - * - * Change the object to which @weak_ref points, or set it to - * %NULL. - * - * You must own a strong reference on @object while calling this - * function. - * - * Since: 2.32 - */ - - - -/************************************************************/ -/* THIS FILE IS GENERATED DO NOT EDIT */ -/************************************************************/ diff --git a/gir/meson.build b/gir/meson.build index 5d646335..dcf65e72 100644 --- a/gir/meson.build +++ b/gir/meson.build @@ -52,12 +52,12 @@ scanner_command = [ ] dep_type = glib_dep.type_name() +# XXX: Instead of hard-coding the subproject directory, we should use +# gnome.generate_gir() because that will take care of dependencies, include +# paths, library paths, and more that we now have to handle manually when +# building with subprojects. +subprojdir = 'subprojects' if dep_type == 'internal' - # XXX: Instead of hard-coding the subproject directory, we should use - # gnome.generate_gir() because that will take care of dependencies, include - # paths, library paths, and more that we now have to handle manually when - # building with subprojects. - subprojdir = 'subprojects' scanner_command += [ '--extra-library=glib-2.0', '--extra-library=gmodule-2.0', @@ -96,6 +96,33 @@ glib_command = scanner_command + [ '--library=gobject-2.0', ] +glib_srcdir = get_option('glib_src_dir') +if dep_type == 'internal' + # XXX: This is a pile of hacks to allow gobject-introspection to parse the + # GLib source files when GLib is used as a subproject + # Assumes the location of the glib subproject dir + # We should add API to meson to get a specific file from a specific + # subproject + glib_subproject = subproject('glib') + + glibproj_sourcedir = join_paths(meson.source_root(), subprojdir, 'glib') + glibproj_builddir = join_paths(meson.build_root(), subprojdir, 'glib') +endif + +if glib_srcdir == '' + if dep_type == 'pkgconfig' + # Cannot use subproject directly, or Meson will try to “configure” it. + glib_srcdir = join_paths(meson.source_root(), subprojdir, 'glib') + if not fs.is_dir(glib_srcdir) + error('Missing glib subproject required for generating glib GIR files. Either download it, or specify path to source code using glib_src_dir Meson option.') + endif + elif dep_type == 'internal' + glib_srcdir = glibproj_sourcedir + else + error('Unknown glib dependency type: ' + dep_type) + endif +endif + if dep_type == 'pkgconfig' glib_command += ['--external-library', '--pkg=glib-2.0'] glib_libdir = get_option('gi_cross_pkgconfig_sysroot_path') + glib_dep.get_pkgconfig_variable('libdir') @@ -113,14 +140,11 @@ if dep_type == 'pkgconfig' endif glib_headers = ret.stdout().strip().split('\n') # Get a list of all source files - glib_srcdir = get_option('glib_src_dir') - if glib_srcdir != '' - ret = run_command(python, '-c', globber.format(join_paths(glib_srcdir, 'glib', '*.c'))) - if ret.returncode() != 0 - error('Failed to get glib source list') - endif - glib_files += ret.stdout().strip().split('\n') + ret = run_command(python, '-c', globber.format(join_paths(glib_srcdir, 'glib', '*.c'))) + if ret.returncode() != 0 + error('Failed to get glib source list') endif + glib_files += ret.stdout().strip().split('\n') glib_includes = ['-I' + glib_incdir, '-I' + glib_libincdir] glib_gir_dep = [] elif dep_type == 'internal' @@ -131,11 +155,6 @@ elif dep_type == 'internal' # We should add API to meson to get a specific file from a specific # subproject # We know exactly what headers will be installed, so just fetch that - glib_subproject = subproject('glib') - - glibproj_sourcedir = join_paths(meson.source_root(), subprojdir, 'glib') - glibproj_builddir = join_paths(meson.build_root(), subprojdir, 'glib') - glib_files += join_paths(glibproj_sourcedir, 'gobject', 'glib-types.h') # Generated files, relative to the build directory @@ -211,11 +230,6 @@ foreach h : glib_headers endif endforeach -# NOTE: Always add this last so that we prefer the annotations in the sources -# (if they are available) since it contains 'backup' annotations that can be -# out of date. -glib_files += files('glib-2.0.c') - gir_giscanner_pymod = [] gir_giscanner_built_files = [] if not get_option('gi_cross_use_prebuilt_gi') @@ -262,13 +276,11 @@ if dep_type == 'pkgconfig' error('Failed to get gobject header list') endif gobject_headers = ret.stdout().strip().split('\n') - if glib_srcdir != '' - ret = run_command(python, '-c', globber.format(join_paths(glib_srcdir, 'gobject', '*.c'))) - if ret.returncode() != 0 - error('Failed to get gobject source list') - endif - gobject_files += ret.stdout().strip().split('\n') + ret = run_command(python, '-c', globber.format(join_paths(glib_srcdir, 'gobject', '*.c'))) + if ret.returncode() != 0 + error('Failed to get gobject source list') endif + gobject_files += ret.stdout().strip().split('\n') gobject_gir_dep = [] else gobject_command += ['--pkg-export=gobject-2.0'] @@ -287,11 +299,6 @@ foreach h : gobject_headers endif endforeach -# NOTE: Always add this last so that we prefer the annotations in the sources -# (if they are available) since it contains 'backup' annotations that can be -# out of date. -gobject_files += files('gobject-2.0.c') - gobject_gir = custom_target('gir-gobject', input: gobject_files, output: 'GObject-2.0.gir', @@ -324,9 +331,7 @@ gmodule_command = scanner_command + [ if dep_type == 'pkgconfig' gmodule_command += ['--external-library', '--pkg=gmodule-2.0'] gmodule_files += join_paths(glib_incdir, 'gmodule.h') - if glib_srcdir != '' - gmodule_files += join_paths(glib_srcdir, 'gmodule', 'gmodule.c') - endif + gmodule_files += join_paths(glib_srcdir, 'gmodule', 'gmodule.c') gmodule_gir_dep = [] else gmodule_command += ['--pkg-export=gmodule-2.0'] @@ -339,11 +344,6 @@ else gmodule_gir_dep = glib_subproject.get_variable('libgmodule') endif -# NOTE: Always add this last so that we prefer the annotations in the sources -# (if they are available) since it contains 'backup' annotations that can be -# out of date. -gmodule_files += files('gmodule-2.0.c') - gir_files += custom_target('gir-gmodule', input: gmodule_files, output: 'GModule-2.0.gir', @@ -381,13 +381,11 @@ if dep_type == 'pkgconfig' # Get all gio (and gio-unix) sources. This is not entirely correct, but it's # probably fine since it matches what Autotools does. We are more exact in # the subproject case. - if glib_srcdir != '' - ret = run_command(python, '-c', globber.format(join_paths(glib_srcdir, 'gio', '*.c'))) - if ret.returncode() != 0 - error('Failed to get gio source list') - endif - gio_files += ret.stdout().strip().split('\n') + ret = run_command(python, '-c', globber.format(join_paths(glib_srcdir, 'gio', '*.c'))) + if ret.returncode() != 0 + error('Failed to get gio source list') endif + gio_files += ret.stdout().strip().split('\n') gio_gir_dep = [] else gio_command += ['--pkg-export=gio-2.0'] @@ -434,11 +432,6 @@ if giounix_dep.found() endforeach endif -# NOTE: Always add this last so that we prefer the annotations in the sources -# (if they are available) since it contains 'backup' annotations that can be -# out of date. -gio_files += files('gio-2.0.c') - gio_gir = custom_target('gir-gio', input: gio_files, output: 'Gio-2.0.gir', diff --git a/meson.build b/meson.build index 79532462..c3d64bd4 100644 --- a/meson.build +++ b/meson.build @@ -17,6 +17,8 @@ configinc = include_directories('.') pymod = import('python') python = pymod.find_installation(get_option('python')) +fs = import('fs') + python_version = python.language_version() python_version_req = '>=3.6' if not python_version.version_compare(python_version_req) diff --git a/misc/update-glib-annotations.py b/misc/update-glib-annotations.py deleted file mode 100755 index bfcb5a3e..00000000 --- a/misc/update-glib-annotations.py +++ /dev/null @@ -1,90 +0,0 @@ -#!/usr/bin/env python3 -# Scan glib sources. -# -# meson _build -# ninja -C _build -# ./misc/update-glib-annotations.py <path-to-glib-git-checkout> - -import os -import sys -import subprocess - - -SCRIPT_DIR = os.path.dirname(os.path.realpath(__file__)) -SRC_DIR = os.path.realpath(os.path.join(SCRIPT_DIR, "..")) - - -def get_build_dir(): - build_dir = os.path.join(SRC_DIR, "_build") - if not os.path.isdir(build_dir): - raise SystemExit( - "build dir not found: " - "build with meson in %r first" % build_dir) - return build_dir - - -def get_tool_path(): - build_dir = get_build_dir() - tool_path = os.path.join(build_dir, "tools", "g-ir-annotation-tool") - if not os.path.isfile(tool_path): - raise SystemExit( - "g-ir-annotation-tool not found: " - "build with meson in %r first" % build_dir) - return tool_path - - -def extract_annotations(module_name, glib_srcdir, outfile): - sources = [] - - glib_subdir = os.path.join(glib_srcdir, module_name) - for sourcename in sorted(os.listdir(glib_subdir), reverse=True): - if sourcename.endswith('.c'): - sources.append(os.path.join(glib_subdir, sourcename)) - - env = os.environ.copy() - env['PYTHONPATH'] = os.path.join(get_build_dir(), 'giscanner') - - tool_args = [sys.executable, get_tool_path(), '--extract'] + sources - return subprocess.check_call(tool_args, stdout=outfile, env=env) - - -def update_module(module_name, glib_src_dir, target_path): - tmpname = target_path + '.tmp' - - if os.path.isfile(tmpname): - os.unlink(tmpname) - with open(tmpname, 'wb') as target: - extract_annotations(module_name, glib_src_dir, target) - if os.path.isfile(target_path): - os.unlink(target_path) - os.rename(tmpname, target_path) - - print("Updated '%s'" % (target_path, )) - - -def main(argv): - if len(argv) != 2: - raise SystemExit("only pass the glib src dir") - glib_src_dir = argv[1] - if not os.path.exists(os.path.join(glib_src_dir, "glib.doap")): - raise SystemExit("%s isn't the glib source dir" % glib_src_dir) - - print("Using source directory: '%s' build directory: '%s'" % ( - glib_src_dir, get_build_dir())) - - gir_dir = os.path.join(SRC_DIR, "gir") - modules = { - 'glib': os.path.join(gir_dir, 'glib-2.0.c'), - 'gmodule': os.path.join(gir_dir, 'gmodule-2.0.c'), - 'gobject': os.path.join(gir_dir, 'gobject-2.0.c'), - 'gio': os.path.join(gir_dir, 'gio-2.0.c'), - } - - for module_name, target_path in modules.items(): - update_module(module_name, glib_src_dir, target_path) - - print("Done; run \"git diff\" to see any changes.") - - -if __name__ == '__main__': - main(sys.argv) |