Functions ========= .. currentmodule:: gi.repository.Gio .. function:: action_name_is_valid(action_name: str) -> bool :param action_name: .. function:: action_parse_detailed_name(detailed_name: str) -> ~typing.Tuple[bool, str, ~gi.repository.GLib.Variant | None] :param detailed_name: .. function:: action_print_detailed_name(action_name: str, target_value: ~gi.repository.GLib.Variant | None = None) -> str :param action_name: :param target_value: .. function:: app_info_create_from_commandline(commandline: str, application_name: str | None, flags: ~gi.repository.Gio.AppInfoCreateFlags) -> ~gi.repository.Gio.AppInfo :param commandline: :param application_name: :param flags: .. function:: app_info_get_all() -> list[~gi.repository.Gio.AppInfo] .. function:: app_info_get_all_for_type(content_type: str) -> list[~gi.repository.Gio.AppInfo] :param content_type: .. function:: app_info_get_default_for_type(content_type: str, must_support_uris: bool) -> ~gi.repository.Gio.AppInfo | None :param content_type: :param must_support_uris: .. function:: app_info_get_default_for_type_async(content_type: str, must_support_uris: bool, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None :param content_type: :param must_support_uris: :param cancellable: :param callback: :param user_data: .. function:: app_info_get_default_for_type_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.AppInfo :param result: .. function:: app_info_get_default_for_uri_scheme(uri_scheme: str) -> ~gi.repository.Gio.AppInfo | None :param uri_scheme: .. function:: app_info_get_default_for_uri_scheme_async(uri_scheme: str, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None :param uri_scheme: :param cancellable: :param callback: :param user_data: .. function:: app_info_get_default_for_uri_scheme_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.AppInfo :param result: .. function:: app_info_get_fallback_for_type(content_type: str) -> list[~gi.repository.Gio.AppInfo] :param content_type: .. function:: app_info_get_recommended_for_type(content_type: str) -> list[~gi.repository.Gio.AppInfo] :param content_type: .. function:: app_info_launch_default_for_uri(uri: str, context: ~gi.repository.Gio.AppLaunchContext | None = None) -> bool :param uri: :param context: .. function:: app_info_launch_default_for_uri_async(uri: str, context: ~gi.repository.Gio.AppLaunchContext | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None :param uri: :param context: :param cancellable: :param callback: :param user_data: .. function:: app_info_launch_default_for_uri_finish(result: ~gi.repository.Gio.AsyncResult) -> bool :param result: .. function:: app_info_reset_type_associations(content_type: str) -> None :param content_type: .. function:: async_initable_newv_async(object_type: ~gobject.GType, n_parameters: int, parameters: ~gi.repository.GObject.Parameter, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None :param object_type: :param n_parameters: :param parameters: :param io_priority: :param cancellable: :param callback: :param user_data: .. function:: bus_get(bus_type: ~gi.repository.Gio.BusType, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Asynchronously connects to the message bus specified by ``bus_type``\. When the operation is finished, ``callback`` will be invoked. You can then call :func:`~gi.repository.Gio.bus_get_finish` to get the result of the operation. This is an asynchronous failable function. See :func:`~gi.repository.Gio.bus_get_sync` for the synchronous version. .. versionadded:: 2.26 :param bus_type: a :obj:`~gi.repository.Gio.BusType` :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` or :const:`None` :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the request is satisfied :param user_data: the data to pass to ``callback`` .. function:: bus_get_finish(res: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.DBusConnection Finishes an operation started with :func:`~gi.repository.Gio.bus_get`. The returned object is a singleton, that is, shared with other callers of :func:`~gi.repository.Gio.bus_get` and :func:`~gi.repository.Gio.bus_get_sync` for ``bus_type``\. In the event that you need a private message bus connection, use :func:`~gi.repository.Gio.dbus_address_get_for_bus_sync` and :func:`~gi.repository.Gio.DBusConnection.new_for_address` with G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT and G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags. Note that the returned :obj:`~gi.repository.Gio.DBusConnection` object will (usually) have the :obj:`~gi.repository.Gio.DBusConnection`\:exit-on-close property set to :const:`True`. .. versionadded:: 2.26 :param res: a :obj:`~gi.repository.Gio.AsyncResult` obtained from the :obj:`~gi.repository.Gio.AsyncReadyCallback` passed to :func:`~gi.repository.Gio.bus_get` :return: a :obj:`~gi.repository.Gio.DBusConnection` or :const:`None` if ``error`` is set. Free with :func:`~gi.repository.GObject.GObject.Object.unref`. .. function:: bus_get_sync(bus_type: ~gi.repository.Gio.BusType, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.Gio.DBusConnection 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 :func:`~gi.repository.Gio.bus_get` and :func:`~gi.repository.Gio.bus_get_finish` for the asynchronous version. The returned object is a singleton, that is, shared with other callers of :func:`~gi.repository.Gio.bus_get` and :func:`~gi.repository.Gio.bus_get_sync` for ``bus_type``\. In the event that you need a private message bus connection, use :func:`~gi.repository.Gio.dbus_address_get_for_bus_sync` and :func:`~gi.repository.Gio.DBusConnection.new_for_address` with G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT and G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags. Note that the returned :obj:`~gi.repository.Gio.DBusConnection` object will (usually) have the :obj:`~gi.repository.Gio.DBusConnection`\:exit-on-close property set to :const:`True`. .. versionadded:: 2.26 :param bus_type: a :obj:`~gi.repository.Gio.BusType` :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` or :const:`None` :return: a :obj:`~gi.repository.Gio.DBusConnection` or :const:`None` if ``error`` is set. Free with :func:`~gi.repository.GObject.GObject.Object.unref`. .. function:: bus_own_name(bus_type: ~gi.repository.Gio.BusType, name: str, flags: ~gi.repository.Gio.BusNameOwnerFlags, bus_acquired_closure: ~gi.repository.GObject.Closure | None = None, name_acquired_closure: ~gi.repository.GObject.Closure | None = None, name_lost_closure: ~gi.repository.GObject.Closure | None = None) -> int 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 :const:`None` 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 :func:`~gi.repository.Gio.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 :obj:`~gi.repository.Gio.DBusConnection` 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 :func:`~gi.repository.Gio.bus_own_name` several times for the same name (unless interleaved with calls to :func:`~gi.repository.Gio.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. :func:`~gi.repository.Gio.DBusConnection.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``\. .. versionadded:: 2.26 :param bus_type: the type of bus to own a name on :param name: the well-known name to own :param flags: a set of flags from the :obj:`~gi.repository.Gio.BusNameOwnerFlags` enumeration :param bus_acquired_closure: :param name_acquired_closure: :param name_lost_closure: :return: an identifier (never 0) that can be used with :func:`~gi.repository.Gio.bus_unown_name` to stop owning the name. .. function:: bus_own_name_on_connection(connection: ~gi.repository.Gio.DBusConnection, name: str, flags: ~gi.repository.Gio.BusNameOwnerFlags, name_acquired_closure: ~gi.repository.GObject.Closure | None = None, name_lost_closure: ~gi.repository.GObject.Closure | None = None) -> int Like :func:`~gi.repository.Gio.bus_own_name` but takes a :obj:`~gi.repository.Gio.DBusConnection` instead of a :obj:`~gi.repository.Gio.BusType`\. .. versionadded:: 2.26 :param connection: a :obj:`~gi.repository.Gio.DBusConnection` :param name: the well-known name to own :param flags: a set of flags from the :obj:`~gi.repository.Gio.BusNameOwnerFlags` enumeration :param name_acquired_closure: :param name_lost_closure: :return: an identifier (never 0) that can be used with :func:`~gi.repository.Gio.bus_unown_name` to stop owning the name .. function:: bus_unown_name(owner_id: int) -> None 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 :obj:`~gi.repository.GLib.MainContext` after this function has returned. You should continue to iterate the :obj:`~gi.repository.GLib.MainContext` until the :obj:`~gi.repository.GLib.DestroyNotify` function passed to :func:`~gi.repository.Gio.bus_own_name` is called, in order to avoid memory leaks through callbacks queued on the :obj:`~gi.repository.GLib.MainContext` after it’s stopped being iterated. .. versionadded:: 2.26 :param owner_id: an identifier obtained from :func:`~gi.repository.Gio.bus_own_name` .. function:: bus_unwatch_name(watcher_id: int) -> None 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 :obj:`~gi.repository.GLib.MainContext` after this function has returned. You should continue to iterate the :obj:`~gi.repository.GLib.MainContext` until the :obj:`~gi.repository.GLib.DestroyNotify` function passed to :func:`~gi.repository.Gio.bus_watch_name` is called, in order to avoid memory leaks through callbacks queued on the :obj:`~gi.repository.GLib.MainContext` after it’s stopped being iterated. .. versionadded:: 2.26 :param watcher_id: An identifier obtained from :func:`~gi.repository.Gio.bus_watch_name` .. function:: bus_watch_name(bus_type: ~gi.repository.Gio.BusType, name: str, flags: ~gi.repository.Gio.BusNameWatcherFlags, name_appeared_closure: ~gi.repository.GObject.Closure | None = None, name_vanished_closure: ~gi.repository.GObject.Closure | None = None) -> int 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 :func:`~gi.repository.Gio.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 :obj:`~gi.repository.Gio.DBusConnection` 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``\. .. versionadded:: 2.26 :param bus_type: The type of bus to watch a name on. :param name: The name (well-known or unique) to watch. :param flags: Flags from the :obj:`~gi.repository.Gio.BusNameWatcherFlags` enumeration. :param name_appeared_closure: :param name_vanished_closure: :return: An identifier (never 0) that can be used with :func:`~gi.repository.Gio.bus_unwatch_name` to stop watching the name. .. function:: bus_watch_name_on_connection(connection: ~gi.repository.Gio.DBusConnection, name: str, flags: ~gi.repository.Gio.BusNameWatcherFlags, name_appeared_closure: ~gi.repository.GObject.Closure | None = None, name_vanished_closure: ~gi.repository.GObject.Closure | None = None) -> int Like :func:`~gi.repository.Gio.bus_watch_name` but takes a :obj:`~gi.repository.Gio.DBusConnection` instead of a :obj:`~gi.repository.Gio.BusType`\. .. versionadded:: 2.26 :param connection: A :obj:`~gi.repository.Gio.DBusConnection`\. :param name: The name (well-known or unique) to watch. :param flags: Flags from the :obj:`~gi.repository.Gio.BusNameWatcherFlags` enumeration. :param name_appeared_closure: :param name_vanished_closure: :return: An identifier (never 0) that can be used with :func:`~gi.repository.Gio.bus_unwatch_name` to stop watching the name. .. function:: content_type_can_be_executable(type: str) -> bool 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). :param type: a content type string :return: :const:`True` if the file type corresponds to a type that can be executable, :const:`False` otherwise. .. function:: content_type_equals(type1: str, type2: str) -> bool Compares two content types for equality. :param type1: a content type string :param type2: a content type string :return: :const:`True` if the two strings are identical or equivalent, :const:`False` otherwise. .. function:: content_type_from_mime_type(mime_type: str) -> str | None Tries to find a content type based on the mime type name. .. versionadded:: 2.18 :param mime_type: a mime type string :return: Newly allocated string with content type or :const:`None`. Free with :func:`~gi.repository.GLib.free` .. function:: content_type_get_description(type: str) -> str Gets the human readable description of the content type. :param type: a content type string :return: a short description of the content type ``type``\. Free the returned string with :func:`~gi.repository.GLib.free` .. function:: content_type_get_generic_icon_name(type: str) -> str | None Gets the generic icon name for a content type. See the `shared-mime-info `__ specification for more on the generic icon name. .. versionadded:: 2.34 :param type: a content type string :return: the registered generic icon name for the given ``type``\, or :const:`None` if unknown. Free with :func:`~gi.repository.GLib.free` .. function:: content_type_get_icon(type: str) -> ~gi.repository.Gio.Icon Gets the icon for a content type. :param type: a content type string :return: :obj:`~gi.repository.Gio.Icon` corresponding to the content type. Free the returned object with :func:`~gi.repository.GObject.GObject.Object.unref` .. function:: content_type_get_mime_dirs() -> list[str] Get the list of directories which MIME data is loaded from. See :func:`~gi.repository.Gio.content_type_set_mime_dirs` for details. .. versionadded:: 2.60 :return: :const:`None`-terminated list of directories to load MIME data from, including any ``mime/`` subdirectory, and with the first directory to try listed first .. function:: content_type_get_mime_type(type: str) -> str | None Gets the mime type for the content type, if one is registered. :param type: a content type string :return: the registered mime type for the given ``type``\, or :const:`None` if unknown; free with :func:`~gi.repository.GLib.free`. .. function:: content_type_get_symbolic_icon(type: str) -> ~gi.repository.Gio.Icon Gets the symbolic icon for a content type. .. versionadded:: 2.34 :param type: a content type string :return: symbolic :obj:`~gi.repository.Gio.Icon` corresponding to the content type. Free the returned object with :func:`~gi.repository.GObject.GObject.Object.unref` .. function:: content_type_guess(filename: str | None = None, data: list[int] | None = None) -> ~typing.Tuple[str, bool] Guesses the content type based on example data. If the function is uncertain, ``result_uncertain`` will be set to :const:`True`. Either ``filename`` or ``data`` may be :const:`None`, in which case the guess will be based solely on the other argument. :param filename: a path, or :const:`None` :param data: a stream of data, or :const:`None` :return: a string indicating a guessed content type for the given data. Free with :func:`~gi.repository.GLib.free` .. function:: content_type_guess_for_tree(root: ~gi.repository.Gio.File) -> list[str] 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 `__ specification for more on x-content types. This function is useful in the implementation of :func:`~gi.repository.Gio.Mount.guess_content_type`. .. versionadded:: 2.18 :param root: the root of the tree to guess a type for :return: an :const:`None`-terminated array of zero or more content types. Free with :func:`~gi.repository.GLib.strfreev` .. function:: content_type_is_a(type: str, supertype: str) -> bool Determines if ``type`` is a subset of ``supertype``\. :param type: a content type string :param supertype: a content type string :return: :const:`True` if ``type`` is a kind of ``supertype``\, :const:`False` otherwise. .. function:: content_type_is_mime_type(type: str, mime_type: str) -> bool Determines if ``type`` is a subset of ``mime_type``\. Convenience wrapper around :func:`~gi.repository.Gio.content_type_is_a`. .. versionadded:: 2.52 :param type: a content type string :param mime_type: a mime type string :return: :const:`True` if ``type`` is a kind of ``mime_type``\, :const:`False` otherwise. .. function:: content_type_is_unknown(type: str) -> bool 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. :param type: a content type string :return: :const:`True` if the type is the unknown type. .. function:: content_type_set_mime_dirs(dirs: list[str] | None = None) -> None Set the list of directories used by GIO to load the MIME database. If ``dirs`` is :const:`None`, 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 :const:`None` before calling :func:`~gi.repository.GLib.test_init`, for instance: .. code-block:: C :dedent: // 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 (); .. versionadded:: 2.60 :param dirs: :const:`None`-terminated list of directories to load MIME data from, including any ``mime/`` subdirectory, and with the first directory to try listed first .. function:: content_types_get_registered() -> list[str] 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)``\. :return: list of the registered content types .. function:: dbus_address_escape_value(string: str) -> str 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``\. .. versionadded:: 2.36 :param string: an unescaped string to be included in a D-Bus address as the value in a key-value pair :return: a copy of ``string`` with all non-optionally-escaped bytes escaped .. function:: dbus_address_get_for_bus_sync(bus_type: ~gi.repository.Gio.BusType, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> str 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 `__\. .. versionadded:: 2.26 :param bus_type: a :obj:`~gi.repository.Gio.BusType` :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` or :const:`None` :return: a valid D-Bus address string for ``bus_type`` or :const:`None` if ``error`` is set .. function:: dbus_address_get_stream(address: str, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None 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 `__\. When the operation is finished, ``callback`` will be invoked. You can then call :func:`~gi.repository.Gio.dbus_address_get_stream_finish` to get the result of the operation. This is an asynchronous failable function. See :func:`~gi.repository.Gio.dbus_address_get_stream_sync` for the synchronous version. .. versionadded:: 2.26 :param address: A valid D-Bus address. :param cancellable: A :obj:`~gi.repository.Gio.Cancellable` or :const:`None`. :param callback: A :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the request is satisfied. :param user_data: Data to pass to ``callback``\. .. function:: dbus_address_get_stream_finish(res: ~gi.repository.Gio.AsyncResult) -> ~typing.Tuple[~gi.repository.Gio.IOStream, str | None] Finishes an operation started with :func:`~gi.repository.Gio.dbus_address_get_stream`. A server is not required to set a GUID, so ``out_guid`` may be set to :const:`None` even on success. .. versionadded:: 2.26 :param res: A :obj:`~gi.repository.Gio.AsyncResult` obtained from the GAsyncReadyCallback passed to :func:`~gi.repository.Gio.dbus_address_get_stream`. :return: A :obj:`~gi.repository.Gio.IOStream` or :const:`None` if ``error`` is set. .. function:: dbus_address_get_stream_sync(address: str, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~typing.Tuple[~gi.repository.Gio.IOStream, str | None] 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 `__\. A server is not required to set a GUID, so ``out_guid`` may be set to :const:`None` even on success. This is a synchronous failable function. See :func:`~gi.repository.Gio.dbus_address_get_stream` for the asynchronous version. .. versionadded:: 2.26 :param address: A valid D-Bus address. :param cancellable: A :obj:`~gi.repository.Gio.Cancellable` or :const:`None`. :return: A :obj:`~gi.repository.Gio.IOStream` or :const:`None` if ``error`` is set. .. function:: dbus_annotation_info_lookup(annotations: list[~gi.repository.Gio.DBusAnnotationInfo] | None, name: str) -> str | None :param annotations: :param name: .. function:: dbus_error_encode_gerror(error: ~gi.repository.GLib.GError) -> str :param error: .. function:: dbus_error_get_remote_error(error: ~gi.repository.GLib.GError) -> str | None :param error: .. function:: dbus_error_is_remote_error(error: ~gi.repository.GLib.GError) -> bool :param error: .. function:: dbus_error_new_for_dbus_error(dbus_error_name: str, dbus_error_message: str) -> ~gi.repository.GLib.GError :param dbus_error_name: :param dbus_error_message: .. function:: dbus_error_quark() -> int .. function:: dbus_error_register_error(error_domain: int, error_code: int, dbus_error_name: str) -> bool :param error_domain: :param error_code: :param dbus_error_name: .. function:: dbus_error_register_error_domain(error_domain_quark_name: str, quark_volatile: int, entries: list[~gi.repository.Gio.DBusErrorEntry]) -> None :param error_domain_quark_name: :param quark_volatile: :param entries: .. function:: dbus_error_strip_remote_error(error: ~gi.repository.GLib.GError) -> bool :param error: .. function:: dbus_error_unregister_error(error_domain: int, error_code: int, dbus_error_name: str) -> bool :param error_domain: :param error_code: :param dbus_error_name: .. function:: dbus_escape_object_path(s: str) -> str This is a language binding friendly version of :func:`~gi.repository.Gio.dbus_escape_object_path_bytestring`. .. versionadded:: 2.68 :param s: the string to escape :return: an escaped version of ``s``\. Free with :func:`~gi.repository.GLib.free`. .. function:: dbus_escape_object_path_bytestring(bytes: list[int]) -> str 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 :func:`~gi.repository.GLib.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 :func:`~gi.repository.Gio.dbus_unescape_object_path`. .. versionadded:: 2.68 :param bytes: the string of bytes to escape :return: an escaped version of ``bytes``\. Free with :func:`~gi.repository.GLib.free`. .. function:: dbus_generate_guid() -> str Generate a D-Bus GUID that can be used with e.g. :func:`~gi.repository.Gio.DBusConnection.new`. See the `D-Bus specification `__ 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 `__\. .. versionadded:: 2.26 :return: A valid D-Bus GUID. Free with :func:`~gi.repository.GLib.free`. .. function:: dbus_gvalue_to_gvariant(gvalue: ~gi.repository.GObject.Value, type: ~gi.repository.GLib.VariantType) -> ~gi.repository.GLib.Variant Converts a :obj:`~gi.repository.GObject.Value` to a :obj:`~gi.repository.GLib.Variant` 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 :obj:`~gi.repository.GLib.VariantType` This can fail if e.g. ``gvalue`` is of type :obj:`str` and ``type`` is 'i', i.e. %G_VARIANT_TYPE_INT32. It will also fail for any :obj:`~gi.repository.GObject.Type` (including e.g. :obj:`object` and ``Boxed`` derived-types) not in the table above. Note that if ``gvalue`` is of type %G_TYPE_VARIANT and its value is :const:`None`, the empty :obj:`~gi.repository.GLib.Variant` instance (never :const:`None`) 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 :func:`~gi.repository.Gio.dbus_gvariant_to_gvalue` function for how to convert a :obj:`~gi.repository.GLib.Variant` to a :obj:`~gi.repository.GObject.Value`\. .. versionadded:: 2.30 :param gvalue: A :obj:`~gi.repository.GObject.Value` to convert to a :obj:`~gi.repository.GLib.Variant` :param type: A :obj:`~gi.repository.GLib.VariantType` :return: A :obj:`~gi.repository.GLib.Variant` (never floating) of :obj:`~gi.repository.GLib.VariantType` ``type`` holding the data from ``gvalue`` or an empty :obj:`~gi.repository.GLib.Variant` in case of failure. Free with :func:`~gi.repository.GLib.Variant.unref`. .. function:: dbus_gvariant_to_gvalue(value: ~gi.repository.GLib.Variant) -> ~gi.repository.GObject.Value Converts a :obj:`~gi.repository.GLib.Variant` to a :obj:`~gi.repository.GObject.Value`\. If ``value`` is floating, it is consumed. The rules specified in the :func:`~gi.repository.Gio.dbus_gvalue_to_gvariant` function are used - this function is essentially its reverse form. So, a :obj:`~gi.repository.GLib.Variant` containing any basic or string array type will be converted to a :obj:`~gi.repository.GObject.Value` containing a basic value or string array. Any other :obj:`~gi.repository.GLib.Variant` (handle, variant, tuple, dict entry) will be converted to a :obj:`~gi.repository.GObject.Value` containing that :obj:`~gi.repository.GLib.Variant`\. The conversion never fails - a valid :obj:`~gi.repository.GObject.Value` is always returned in ``out_gvalue``\. .. versionadded:: 2.30 :param value: A :obj:`~gi.repository.GLib.Variant`\. .. function:: dbus_is_address(string: str) -> bool Checks if ``string`` is a `D-Bus address `__\. This doesn't check if ``string`` is actually supported by :obj:`~gi.repository.Gio.DBusServer` or :obj:`~gi.repository.Gio.DBusConnection` - use :func:`~gi.repository.Gio.dbus_is_supported_address` to do more checks. .. versionadded:: 2.26 :param string: A string. :return: :const:`True` if ``string`` is a valid D-Bus address, :const:`False` otherwise. .. function:: dbus_is_error_name(string: str) -> bool Check whether ``string`` is a valid D-Bus error name. This function returns the same result as :func:`~gi.repository.Gio.dbus_is_interface_name`, because D-Bus error names are defined to have exactly the same syntax as interface names. .. versionadded:: 2.70 :param string: The string to check. :return: :const:`True` if valid, :const:`False` otherwise. .. function:: dbus_is_guid(string: str) -> bool Checks if ``string`` is a D-Bus GUID. See the documentation for :func:`~gi.repository.Gio.dbus_generate_guid` for more information about the format of a GUID. .. versionadded:: 2.26 :param string: The string to check. :return: :const:`True` if ``string`` is a GUID, :const:`False` otherwise. .. function:: dbus_is_interface_name(string: str) -> bool Checks if ``string`` is a valid D-Bus interface name. .. versionadded:: 2.26 :param string: The string to check. :return: :const:`True` if valid, :const:`False` otherwise. .. function:: dbus_is_member_name(string: str) -> bool Checks if ``string`` is a valid D-Bus member (e.g. signal or method) name. .. versionadded:: 2.26 :param string: The string to check. :return: :const:`True` if valid, :const:`False` otherwise. .. function:: dbus_is_name(string: str) -> bool Checks if ``string`` is a valid D-Bus bus name (either unique or well-known). .. versionadded:: 2.26 :param string: The string to check. :return: :const:`True` if valid, :const:`False` otherwise. .. function:: dbus_is_supported_address(string: str) -> bool Like :func:`~gi.repository.Gio.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 `__\. .. versionadded:: 2.26 :param string: A string. :return: :const:`True` if ``string`` is a valid D-Bus address that is supported by this library, :const:`False` if ``error`` is set. .. function:: dbus_is_unique_name(string: str) -> bool Checks if ``string`` is a valid D-Bus unique bus name. .. versionadded:: 2.26 :param string: The string to check. :return: :const:`True` if valid, :const:`False` otherwise. .. function:: dbus_unescape_object_path(s: str) -> list[int] | None Unescapes an string that was previously escaped with :func:`~gi.repository.Gio.dbus_escape_object_path`. If the string is in a format that could not have been returned by :func:`~gi.repository.Gio.dbus_escape_object_path`, this function returns :const:`None`. 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). .. versionadded:: 2.68 :param s: the string to unescape :return: an unescaped version of ``s``\, or :const:`None` if ``s`` is not a string returned from :func:`~gi.repository.Gio.dbus_escape_object_path`. Free with :func:`~gi.repository.GLib.free`. .. function:: dtls_client_connection_new(base_socket: ~gi.repository.Gio.DatagramBased, server_identity: ~gi.repository.Gio.SocketConnectable | None = None) -> ~gi.repository.Gio.DtlsClientConnection :param base_socket: :param server_identity: .. function:: dtls_server_connection_new(base_socket: ~gi.repository.Gio.DatagramBased, certificate: ~gi.repository.Gio.TlsCertificate | None = None) -> ~gi.repository.Gio.DtlsServerConnection :param base_socket: :param certificate: .. function:: file_new_build_filenamev(args: list[str]) -> ~gi.repository.Gio.File :param args: .. function:: file_new_for_commandline_arg(arg: str) -> ~gi.repository.Gio.File :param arg: .. function:: file_new_for_commandline_arg_and_cwd(arg: str, cwd: str) -> ~gi.repository.Gio.File :param arg: :param cwd: .. function:: file_new_for_path(path: str) -> ~gi.repository.Gio.File :param path: .. function:: file_new_for_uri(uri: str) -> ~gi.repository.Gio.File :param uri: .. function:: file_new_tmp(tmpl: str | None = None) -> ~typing.Tuple[~gi.repository.Gio.File, ~gi.repository.Gio.FileIOStream] :param tmpl: .. function:: file_new_tmp_async(tmpl: str | None, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None :param tmpl: :param io_priority: :param cancellable: :param callback: :param user_data: .. function:: file_new_tmp_dir_async(tmpl: str | None, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None :param tmpl: :param io_priority: :param cancellable: :param callback: :param user_data: .. function:: file_new_tmp_dir_finish(result: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.File :param result: .. function:: file_new_tmp_finish(result: ~gi.repository.Gio.AsyncResult) -> ~typing.Tuple[~gi.repository.Gio.File, ~gi.repository.Gio.FileIOStream] :param result: .. function:: file_parse_name(parse_name: str) -> ~gi.repository.Gio.File :param parse_name: .. function:: icon_deserialize(value: ~gi.repository.GLib.Variant) -> ~gi.repository.Gio.Icon | None :param value: .. function:: icon_new_for_string(str: str) -> ~gi.repository.Gio.Icon :param str: .. function:: initable_newv(object_type: ~gobject.GType, parameters: list[~gi.repository.GObject.Parameter], cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.GObject.Object :param object_type: :param parameters: :param cancellable: .. function:: io_error_from_errno(err_no: int) -> ~gi.repository.Gio.IOErrorEnum Converts ``errno.h`` error codes into GIO error codes. The fallback value :const:`~gi.repository.Gio.IOErrorEnum.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 immediately after the call returns, and use the saved value instead of ``errno``\: .. code-block:: C :dedent: int saved_errno; ret = read (blah); saved_errno = errno; g_io_error_from_errno (saved_errno); :param err_no: Error number as defined in errno.h. :return: :obj:`~gi.repository.Gio.IOErrorEnum` value for the given ``errno.h`` error number .. function:: io_error_from_file_error(file_error: ~gi.repository.GLib.FileError) -> ~gi.repository.Gio.IOErrorEnum Converts :obj:`~gi.repository.GLib.FileError` error codes into GIO error codes. .. versionadded:: 2.74 :param file_error: a :obj:`~gi.repository.GLib.FileError`\. :return: :obj:`~gi.repository.Gio.IOErrorEnum` value for the given :obj:`~gi.repository.GLib.FileError` error value. .. function:: io_error_quark() -> int Gets the GIO Error Quark. :return: a :obj:`~gi.repository.GLib.Quark`\. .. function:: io_extension_point_implement(extension_point_name: str, type: ~gobject.GType, extension_name: str, priority: int) -> ~gi.repository.Gio.IOExtension :param extension_point_name: :param type: :param extension_name: :param priority: .. function:: io_extension_point_lookup(name: str) -> ~gi.repository.Gio.IOExtensionPoint :param name: .. function:: io_extension_point_register(name: str) -> ~gi.repository.Gio.IOExtensionPoint :param name: .. function:: io_modules_load_all_in_directory(dirname: str) -> list[~gi.repository.Gio.IOModule] 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 :func:`~gi.repository.Gio.io_modules_scan_all_in_directory` which allows delayed/lazy loading of modules. :param dirname: pathname for a directory containing modules to load. :return: a list of :obj:`~gi.repository.Gio.IOModule` loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call :func:`~gi.repository.GObject.GObject.TypeModule.unuse` on all the modules. Free the list with :func:`~gi.repository.GLib.List.free`. .. function:: io_modules_load_all_in_directory_with_scope(dirname: str, scope: ~gi.repository.Gio.IOModuleScope) -> list[~gi.repository.Gio.IOModule] 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 :func:`~gi.repository.Gio.io_modules_scan_all_in_directory` which allows delayed/lazy loading of modules. .. versionadded:: 2.30 :param dirname: pathname for a directory containing modules to load. :param scope: a scope to use when scanning the modules. :return: a list of :obj:`~gi.repository.Gio.IOModule` loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call :func:`~gi.repository.GObject.GObject.TypeModule.unuse` on all the modules. Free the list with :func:`~gi.repository.GLib.List.free`. .. function:: io_modules_scan_all_in_directory(dirname: str) -> None 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. :func:`~gi.repository.Gio.IOExtensionPoint.get_extensions` or :func:`~gi.repository.Gio.IOExtensionPoint.get_extension_by_name`. If you need to guarantee that all types are loaded in all the modules, use :func:`~gi.repository.Gio.io_modules_load_all_in_directory`. .. versionadded:: 2.24 :param dirname: pathname for a directory containing modules to scan. .. function:: io_modules_scan_all_in_directory_with_scope(dirname: str, scope: ~gi.repository.Gio.IOModuleScope) -> None 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. :func:`~gi.repository.Gio.IOExtensionPoint.get_extensions` or :func:`~gi.repository.Gio.IOExtensionPoint.get_extension_by_name`. If you need to guarantee that all types are loaded in all the modules, use :func:`~gi.repository.Gio.io_modules_load_all_in_directory`. .. versionadded:: 2.30 :param dirname: pathname for a directory containing modules to scan. :param scope: a scope to use when scanning the modules .. function:: io_scheduler_cancel_all_jobs() -> None Cancels all cancellable I/O jobs. A job is cancellable if a :obj:`~gi.repository.Gio.Cancellable` was passed into :func:`~gi.repository.Gio.io_scheduler_push_job`. .. deprecated:: 2.36 You should never call this function, since you don't know how other libraries in your program might be making use of gioscheduler. .. function:: io_scheduler_push_job(job_func: ~typing.Callable[[~gi.repository.Gio.IOSchedulerJob, ~gi.repository.Gio.Cancellable | None, ~typing.Any], bool], user_data: ~typing.Any, io_priority: int, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> None 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 :const:`None`, it can be used to cancel the I/O job by calling :func:`~gi.repository.Gio.Cancellable.cancel` or by calling :func:`~gi.repository.Gio.io_scheduler_cancel_all_jobs`. .. deprecated:: 2.36 use :obj:`~gi.repository.GLib.ThreadPool` or :func:`~gi.repository.Gio.Task.run_in_thread` :param job_func: a :obj:`~gi.repository.Gio.IOSchedulerJobFunc`\. :param user_data: data to pass to ``job_func`` :param io_priority: the `I/O priority `__ of the request. :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. .. function:: keyfile_settings_backend_new(filename: str, root_path: str, root_group: str | None = None) -> ~gi.repository.Gio.SettingsBackend Creates a keyfile-backed :obj:`~gi.repository.Gio.SettingsBackend`\. 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-:const:`None` 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 :const:`True` will cause the following to appear in the keyfile: .. code-block:: :dedent: [toplevel] enabled=true If ``root_group`` is :const:`None` 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: .. code-block:: :dedent: [profiles/default] font-size=12 The backend will refuse writes (and return writability as being :const:`False`) for keys outside of ``root_path`` and, in the event that ``root_group`` is :const:`None`, 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. :param filename: the filename of the keyfile :param root_path: the path under which all settings keys appear :param root_group: the group name corresponding to ``root_path``\, or :const:`None` :return: a keyfile-backed :obj:`~gi.repository.Gio.SettingsBackend` .. function:: memory_monitor_dup_default() -> ~gi.repository.Gio.MemoryMonitor .. function:: memory_settings_backend_new() -> ~gi.repository.Gio.SettingsBackend Creates a memory-backed :obj:`~gi.repository.Gio.SettingsBackend`\. 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. .. versionadded:: 2.28 :return: a newly created :obj:`~gi.repository.Gio.SettingsBackend` .. function:: network_monitor_get_default() -> ~gi.repository.Gio.NetworkMonitor .. function:: networking_init() -> None 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). .. versionadded:: 2.36 .. function:: null_settings_backend_new() -> ~gi.repository.Gio.SettingsBackend Creates a readonly :obj:`~gi.repository.Gio.SettingsBackend`\. This backend does not allow changes to settings, so all settings will always have their default values. .. versionadded:: 2.28 :return: a newly created :obj:`~gi.repository.Gio.SettingsBackend` .. function:: pollable_source_new(pollable_stream: ~gi.repository.GObject.Object) -> ~gi.repository.GLib.Source Utility method for :obj:`~gi.repository.Gio.PollableInputStream` and :obj:`~gi.repository.Gio.PollableOutputStream` implementations. Creates a new :obj:`~gi.repository.GLib.Source` that expects a callback of type ``GPollableSourceFunc``. The new source does not actually do anything on its own; use :func:`~gi.repository.GLib.Source.add_child_source` to add other sources to it to cause it to trigger. .. versionadded:: 2.28 :param pollable_stream: the stream associated with the new source :return: the new :obj:`~gi.repository.GLib.Source`\. .. function:: pollable_source_new_full(pollable_stream: ~gi.repository.GObject.Object, child_source: ~gi.repository.GLib.Source | None = None, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.GLib.Source Utility method for :obj:`~gi.repository.Gio.PollableInputStream` and :obj:`~gi.repository.Gio.PollableOutputStream` implementations. Creates a new :obj:`~gi.repository.GLib.Source`\, as with :func:`~gi.repository.Gio.pollable_source_new`, but also attaching ``child_source`` (with a dummy callback), and ``cancellable``\, if they are non-:const:`None`. .. versionadded:: 2.34 :param pollable_stream: the stream associated with the new source :param child_source: optional child source to attach :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` to attach :return: the new :obj:`~gi.repository.GLib.Source`\. .. function:: pollable_stream_read(stream: ~gi.repository.Gio.InputStream, buffer: list[int], blocking: bool, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> int Tries to read from ``stream``\, as with :func:`~gi.repository.Gio.InputStream.read` (if ``blocking`` is :const:`True`) or :func:`~gi.repository.Gio.PollableInputStream.read_nonblocking` (if ``blocking`` is :const:`False`). This can be used to more easily share code between blocking and non-blocking implementations of a method. If ``blocking`` is :const:`False`, then ``stream`` must be a :obj:`~gi.repository.Gio.PollableInputStream` for which :func:`~gi.repository.Gio.PollableInputStream.can_poll` returns :const:`True`, or else the behavior is undefined. If ``blocking`` is :const:`True`, then ``stream`` does not need to be a :obj:`~gi.repository.Gio.PollableInputStream`\. .. versionadded:: 2.34 :param stream: a :obj:`~gi.repository.Gio.InputStream` :param buffer: a buffer to read data into :param blocking: whether to do blocking I/O :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :return: the number of bytes read, or -1 on error. .. function:: pollable_stream_write(stream: ~gi.repository.Gio.OutputStream, buffer: list[int], blocking: bool, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> int Tries to write to ``stream``\, as with :func:`~gi.repository.Gio.OutputStream.write` (if ``blocking`` is :const:`True`) or :func:`~gi.repository.Gio.PollableOutputStream.write_nonblocking` (if ``blocking`` is :const:`False`). This can be used to more easily share code between blocking and non-blocking implementations of a method. If ``blocking`` is :const:`False`, then ``stream`` must be a :obj:`~gi.repository.Gio.PollableOutputStream` for which :func:`~gi.repository.Gio.PollableOutputStream.can_poll` returns :const:`True` or else the behavior is undefined. If ``blocking`` is :const:`True`, then ``stream`` does not need to be a :obj:`~gi.repository.Gio.PollableOutputStream`\. .. versionadded:: 2.34 :param stream: a :obj:`~gi.repository.Gio.OutputStream`\. :param buffer: the buffer containing the data to write. :param blocking: whether to do blocking I/O :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :return: the number of bytes written, or -1 on error. .. function:: pollable_stream_write_all(stream: ~gi.repository.Gio.OutputStream, buffer: list[int], blocking: bool, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~typing.Tuple[bool, int] Tries to write ``count`` bytes to ``stream``\, as with :func:`~gi.repository.Gio.OutputStream.write_all`, but using :func:`~gi.repository.Gio.pollable_stream_write` rather than :func:`~gi.repository.Gio.OutputStream.write`. On a successful write of ``count`` bytes, :const:`True` is returned, and ``bytes_written`` is set to ``count``\. If there is an error during the operation (including :const:`~gi.repository.Gio.IOErrorEnum.WOULD_BLOCK` in the non-blocking case), :const:`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 :func:`~gi.repository.Gio.pollable_stream_write`, if ``blocking`` is :const:`False`, then ``stream`` must be a :obj:`~gi.repository.Gio.PollableOutputStream` for which :func:`~gi.repository.Gio.PollableOutputStream.can_poll` returns :const:`True` or else the behavior is undefined. If ``blocking`` is :const:`True`, then ``stream`` does not need to be a :obj:`~gi.repository.Gio.PollableOutputStream`\. .. versionadded:: 2.34 :param stream: a :obj:`~gi.repository.Gio.OutputStream`\. :param buffer: the buffer containing the data to write. :param blocking: whether to do blocking I/O :param cancellable: optional :obj:`~gi.repository.Gio.Cancellable` object, :const:`None` to ignore. :return: :const:`True` on success, :const:`False` if there was an error .. function:: power_profile_monitor_dup_default() -> ~gi.repository.Gio.PowerProfileMonitor .. function:: proxy_get_default_for_protocol(protocol: str) -> ~gi.repository.Gio.Proxy | None :param protocol: .. function:: proxy_resolver_get_default() -> ~gi.repository.Gio.ProxyResolver .. function:: resolver_error_quark() -> int .. function:: resource_error_quark() -> int .. function:: resource_load(filename: str) -> ~gi.repository.Gio.Resource :param filename: .. function:: resources_enumerate_children(path: str, lookup_flags: ~gi.repository.Gio.ResourceLookupFlags) -> list[str] Returns all the names of children at the specified ``path`` in the set of globally registered resources. The return result is a :const:`None` terminated list of strings which should be released with :func:`~gi.repository.GLib.strfreev`. ``lookup_flags`` controls the behaviour of the lookup. .. versionadded:: 2.32 :param path: A pathname inside the resource :param lookup_flags: A :obj:`~gi.repository.Gio.ResourceLookupFlags` :return: an array of constant strings .. function:: resources_get_info(path: str, lookup_flags: ~gi.repository.Gio.ResourceLookupFlags) -> ~typing.Tuple[bool, int, int] 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. .. versionadded:: 2.32 :param path: A pathname inside the resource :param lookup_flags: A :obj:`~gi.repository.Gio.ResourceLookupFlags` :return: :const:`True` if the file was found. :const:`False` if there were errors .. function:: resources_lookup_data(path: str, lookup_flags: ~gi.repository.Gio.ResourceLookupFlags) -> ~gi.repository.GLib.Bytes Looks for a file at the specified ``path`` in the set of globally registered resources and returns a :obj:`~gi.repository.GLib.Bytes` 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. .. versionadded:: 2.32 :param path: A pathname inside the resource :param lookup_flags: A :obj:`~gi.repository.Gio.ResourceLookupFlags` :return: :obj:`~gi.repository.GLib.Bytes` or :const:`None` on error. Free the returned object with :func:`~gi.repository.GLib.Bytes.unref` .. function:: resources_open_stream(path: str, lookup_flags: ~gi.repository.Gio.ResourceLookupFlags) -> ~gi.repository.Gio.InputStream Looks for a file at the specified ``path`` in the set of globally registered resources and returns a :obj:`~gi.repository.Gio.InputStream` that lets you read the data. ``lookup_flags`` controls the behaviour of the lookup. .. versionadded:: 2.32 :param path: A pathname inside the resource :param lookup_flags: A :obj:`~gi.repository.Gio.ResourceLookupFlags` :return: :obj:`~gi.repository.Gio.InputStream` or :const:`None` on error. Free the returned object with :func:`~gi.repository.GObject.GObject.Object.unref` .. function:: resources_register(resource: ~gi.repository.Gio.Resource) -> None 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 :func:`~gi.repository.Gio.resources_lookup_data`. .. versionadded:: 2.32 :param resource: A :obj:`~gi.repository.Gio.Resource` .. function:: resources_unregister(resource: ~gi.repository.Gio.Resource) -> None Unregisters the resource from the process-global set of resources. .. versionadded:: 2.32 :param resource: A :obj:`~gi.repository.Gio.Resource` .. function:: settings_schema_source_get_default() -> ~gi.repository.Gio.SettingsSchemaSource | None .. function:: simple_async_report_gerror_in_idle(object: ~gi.repository.GObject.Object | None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None, user_data: ~typing.Any, error: ~gi.repository.GLib.GError) -> None Reports an error in an idle function. Similar to :func:`~gi.repository.Gio.simple_async_report_error_in_idle`, but takes a :obj:`~gi.repository.GLib.Error` rather than building a new one. .. deprecated:: 2.46 Use :func:`~gi.repository.Gio.Task.report_error`. :param object: a :obj:`~gi.repository.GObject.Object`\, or :const:`None` :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback`\. :param user_data: user data passed to ``callback``\. :param error: the :obj:`~gi.repository.GLib.Error` to report .. function:: tls_backend_get_default() -> ~gi.repository.Gio.TlsBackend .. function:: tls_channel_binding_error_quark() -> int .. function:: tls_client_connection_new(base_io_stream: ~gi.repository.Gio.IOStream, server_identity: ~gi.repository.Gio.SocketConnectable | None = None) -> ~gi.repository.Gio.TlsClientConnection :param base_io_stream: :param server_identity: .. function:: tls_error_quark() -> int .. function:: tls_file_database_new(anchors: str) -> ~gi.repository.Gio.TlsFileDatabase :param anchors: .. function:: tls_server_connection_new(base_io_stream: ~gi.repository.Gio.IOStream, certificate: ~gi.repository.Gio.TlsCertificate | None = None) -> ~gi.repository.Gio.TlsServerConnection :param base_io_stream: :param certificate: .. function:: unix_is_mount_path_system_internal(mount_path: str) -> bool 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. :param mount_path: a mount path, e.g. ``/media/disk`` or ``/usr`` :return: :const:`True` if ``mount_path`` is considered an implementation detail of the OS. .. function:: unix_is_system_device_path(device_path: str) -> bool 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. .. versionadded:: 2.56 :param device_path: a device path, e.g. ``/dev/loop0`` or ``nfsd`` :return: :const:`True` if ``device_path`` is considered an implementation detail of the OS. .. function:: unix_is_system_fs_type(fs_type: str) -> bool 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. .. versionadded:: 2.56 :param fs_type: a file system type, e.g. ``procfs`` or ``tmpfs`` :return: :const:`True` if ``fs_type`` is considered an implementation detail of the OS. .. function:: unix_mount_at(mount_path: str) -> ~typing.Tuple[~gi.repository.Gio.UnixMountEntry | None, int] Gets a :obj:`~gi.repository.Gio.UnixMountEntry` 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 :func:`~gi.repository.Gio.unix_mounts_changed_since`. If more mounts have the same mount path, the last matching mount is returned. This will return :const:`None` if there is no mount point at ``mount_path``\. :param mount_path: path for a possible unix mount. :return: a :obj:`~gi.repository.Gio.UnixMountEntry`\. .. function:: unix_mount_compare(mount1: ~gi.repository.Gio.UnixMountEntry, mount2: ~gi.repository.Gio.UnixMountEntry) -> int Compares two unix mounts. :param mount1: first :obj:`~gi.repository.Gio.UnixMountEntry` to compare. :param mount2: second :obj:`~gi.repository.Gio.UnixMountEntry` to compare. :return: 1, 0 or -1 if ``mount1`` is greater than, equal to, or less than ``mount2``\, respectively. .. function:: unix_mount_for(file_path: str) -> ~typing.Tuple[~gi.repository.Gio.UnixMountEntry | None, int] Gets a :obj:`~gi.repository.Gio.UnixMountEntry` 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 :func:`~gi.repository.Gio.unix_mounts_changed_since`. If more mounts have the same mount path, the last matching mount is returned. This will return :const:`None` if looking up the mount entry fails, if ``file_path`` doesn’t exist or there is an I/O error. .. versionadded:: 2.52 :param file_path: file path on some unix mount. :return: a :obj:`~gi.repository.Gio.UnixMountEntry`\. .. function:: unix_mount_free(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> None Frees a unix mount. :param mount_entry: a :obj:`~gi.repository.Gio.UnixMountEntry`\. .. function:: unix_mount_get_device_path(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> str Gets the device path for a unix mount. :param mount_entry: a ``GUnixMount``. :return: a string containing the device path. .. function:: unix_mount_get_fs_type(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> str Gets the filesystem type for the unix mount. :param mount_entry: a ``GUnixMount``. :return: a string containing the file system type. .. function:: unix_mount_get_mount_path(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> str Gets the mount path for a unix mount. :param mount_entry: input :obj:`~gi.repository.Gio.UnixMountEntry` to get the mount path for. :return: the mount path for ``mount_entry``\. .. function:: unix_mount_get_options(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> str | None Gets a comma-separated list of mount options for the unix mount. For example, ``rw,relatime,seclabel,data=ordered``\. This is similar to :func:`~gi.repository.Gio.UnixMountPoint.get_options`, but it takes a :obj:`~gi.repository.Gio.UnixMountEntry` as an argument. .. versionadded:: 2.58 :param mount_entry: a :obj:`~gi.repository.Gio.UnixMountEntry`\. :return: a string containing the options, or :const:`None` if not available. .. function:: unix_mount_get_root_path(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> str | None 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". .. versionadded:: 2.60 :param mount_entry: a :obj:`~gi.repository.Gio.UnixMountEntry`\. :return: a string containing the root, or :const:`None` if not supported. .. function:: unix_mount_guess_can_eject(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> bool Guesses whether a Unix mount can be ejected. :param mount_entry: a :obj:`~gi.repository.Gio.UnixMountEntry` :return: :const:`True` if ``mount_entry`` is deemed to be ejectable. .. function:: unix_mount_guess_icon(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> ~gi.repository.Gio.Icon Guesses the icon of a Unix mount. :param mount_entry: a :obj:`~gi.repository.Gio.UnixMountEntry` :return: a :obj:`~gi.repository.Gio.Icon` .. function:: unix_mount_guess_name(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> str Guesses the name of a Unix mount. The result is a translated string. :param mount_entry: a :obj:`~gi.repository.Gio.UnixMountEntry` :return: A newly allocated string that must be freed with :func:`~gi.repository.GLib.free` .. function:: unix_mount_guess_should_display(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> bool Guesses whether a Unix mount should be displayed in the UI. :param mount_entry: a :obj:`~gi.repository.Gio.UnixMountEntry` :return: :const:`True` if ``mount_entry`` is deemed to be displayable. .. function:: unix_mount_guess_symbolic_icon(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> ~gi.repository.Gio.Icon Guesses the symbolic icon of a Unix mount. .. versionadded:: 2.34 :param mount_entry: a :obj:`~gi.repository.Gio.UnixMountEntry` :return: a :obj:`~gi.repository.Gio.Icon` .. function:: unix_mount_is_readonly(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> bool Checks if a unix mount is mounted read only. :param mount_entry: a ``GUnixMount``. :return: :const:`True` if ``mount_entry`` is read only. .. function:: unix_mount_is_system_internal(mount_entry: ~gi.repository.Gio.UnixMountEntry) -> bool Checks if a Unix mount is a system mount. This is the Boolean OR of :func:`~gi.repository.Gio.unix_is_system_fs_type`, :func:`~gi.repository.Gio.unix_is_system_device_path` and :func:`~gi.repository.Gio.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. :param mount_entry: a ``GUnixMount``. :return: :const:`True` if the unix mount is for a system path. .. function:: unix_mount_point_at(mount_path: str) -> ~typing.Tuple[~gi.repository.Gio.UnixMountPoint | None, int] :param mount_path: .. function:: unix_mount_points_changed_since(time: int) -> bool Checks if the unix mount points have changed since a given unix time. :param time: guint64 to contain a timestamp. :return: :const:`True` if the mount points have changed since ``time``\. .. function:: unix_mount_points_get() -> ~typing.Tuple[list[~gi.repository.Gio.UnixMountPoint], int] Gets a :obj:`~gi.repository.GLib.List` of :obj:`~gi.repository.Gio.UnixMountPoint` 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 :func:`~gi.repository.Gio.unix_mount_points_changed_since`. :return: a :obj:`~gi.repository.GLib.List` of the UNIX mountpoints. .. function:: unix_mount_points_get_from_file(table_path: str) -> ~typing.Tuple[list[~gi.repository.Gio.UnixMountPoint] | None, int] Gets an array of :obj:`~gi.repository.Gio.UnixMountPoint`\s containing the Unix mount points listed in ``table_path``\. This is a generalized version of :func:`~gi.repository.Gio.unix_mount_points_get`, mainly intended for internal testing use. Note that :func:`~gi.repository.Gio.unix_mount_points_get` may parse multiple hierarchical table files, so this function is not a direct superset of its functionality. If there is an error reading or parsing the file, ``NULL`` will be returned and both out parameters will be set to ``0``\. .. versionadded:: 2.82 :param table_path: path to the mount points table file (for example ``/etc/fstab``\) :return: mount points, or ``NULL`` if there was an error loading them .. function:: unix_mounts_changed_since(time: int) -> bool Checks if the unix mounts have changed since a given unix time. :param time: guint64 to contain a timestamp. :return: :const:`True` if the mounts have changed since ``time``\. .. function:: unix_mounts_get() -> ~typing.Tuple[list[~gi.repository.Gio.UnixMountEntry], int] Gets a :obj:`~gi.repository.GLib.List` of :obj:`~gi.repository.Gio.UnixMountEntry` 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 :func:`~gi.repository.Gio.unix_mounts_changed_since`. :return: a :obj:`~gi.repository.GLib.List` of the UNIX mounts. .. function:: unix_mounts_get_from_file(table_path: str) -> ~typing.Tuple[list[~gi.repository.Gio.UnixMountEntry] | None, int] Gets an array of :obj:`~gi.repository.Gio.UnixMountEntry`\s containing the Unix mounts listed in ``table_path``\. This is a generalized version of :func:`~gi.repository.Gio.unix_mounts_get`, mainly intended for internal testing use. Note that :func:`~gi.repository.Gio.unix_mounts_get` may parse multiple hierarchical table files, so this function is not a direct superset of its functionality. If there is an error reading or parsing the file, ``NULL`` will be returned and both out parameters will be set to ``0``\. .. versionadded:: 2.82 :param table_path: path to the mounts table file (for example ``/proc/self/mountinfo``\) :return: mount entries, or ``NULL`` if there was an error loading them