mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-03-13 11:15:12 +01:00
docs: Port GIO overview to gi-docgen linking syntax and fix a few typos
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
This commit is contained in:
parent
d760bfef00
commit
58c4ab46f2
@ -17,7 +17,7 @@ right level in the library stack, as well as other generally useful APIs
|
||||
for desktop applications (such as networking and D-Bus support). The goal
|
||||
is to overcome the shortcomings of GnomeVFS and provide an API that is so
|
||||
good that developers prefer it over raw POSIX calls. Among other things
|
||||
that means using GObject. It also means not cloning the POSIX API, but
|
||||
that means using [class@GObject.Object]. It also means not cloning the POSIX API, but
|
||||
providing higher-level, document-centric interfaces.
|
||||
|
||||
The abstract file system model of GIO consists of a number of interfaces and
|
||||
@ -71,11 +71,11 @@ There is a framework for storing and retrieving application settings:
|
||||
: stores and retrieves application settings
|
||||
|
||||
There is support for network programming, including connectivity monitoring,
|
||||
name resolution, lowlevel socket APIs and highlevel client and server helper
|
||||
name resolution, low-level socket APIs and high-level client and server helper
|
||||
classes:
|
||||
|
||||
[class@Gio.Socket]
|
||||
: lowlevel platform independent socket object
|
||||
: low-level platform independent socket object
|
||||
|
||||
[class@Gio.Resolver]
|
||||
: asynchronous and cancellable DNS resolver
|
||||
@ -123,14 +123,15 @@ which spawn further mount daemons for each individual connection.
|
||||
|
||||
The GIO model of I/O is stateful: if an application establishes e.g. a SFTP
|
||||
connection to a server, it becomes available to all applications in the
|
||||
session; the user does not have to enter his password over and over again.
|
||||
session; the user does not have to enter their password over and over again.
|
||||
|
||||
One of the big advantages of putting the VFS in the GLib layer is that GTK
|
||||
can directly use it, e.g. in the filechooser.
|
||||
can directly use it, e.g. in the file chooser.
|
||||
|
||||
## Writing GIO applications
|
||||
|
||||
The information in the GLib documentation about writing GLib applications is
|
||||
The information in the GLib documentation about
|
||||
[writing GLib applications](https://docs.gtk.org/glib/programming.html) is
|
||||
generally applicable when writing GIO applications.
|
||||
|
||||
### Threads
|
||||
@ -153,7 +154,7 @@ dispatched, such as input and redraw handlers for the application’s UI. This
|
||||
can cause the application to ‘freeze’ until I/O completes.
|
||||
|
||||
A few self-contained groups of functions, such as code generated by
|
||||
gdbus-codegen, use a different convention: functions are asynchronous
|
||||
[`gdbus-codegen`](gdbus-codegen.html), use a different convention: functions are asynchronous
|
||||
default, and it is the synchronous version which has a `_sync` suffix. Aside
|
||||
from naming differences, they should be treated the same way as functions
|
||||
following the normal convention above.
|
||||
@ -187,10 +188,10 @@ a new user account), there are various ways in which you can go about this:
|
||||
executing the operation.
|
||||
[polkit](https://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html)
|
||||
is a framework that allows this.
|
||||
- Use a small helper that is executed with elevated privileges via pkexec.
|
||||
- Use a small helper that is executed with elevated privileges via `pkexec`.
|
||||
[`pkexec`](https://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html)
|
||||
is a small program launcher that is part of polkit.
|
||||
- Use a small helper that is executed with elevated privileges by being suid
|
||||
- Use a small helper that is executed with elevated privileges by being SUID
|
||||
root.
|
||||
|
||||
None of these approaches is the clear winner, they all have their advantages
|
||||
@ -204,13 +205,13 @@ excellent book on this topic,
|
||||
When using GIO in code that runs with elevated privileges, you have to be
|
||||
careful. GIO has extension points whose implementations get loaded from
|
||||
modules (executable code in shared objects), which could allow an attacker
|
||||
to sneak his own code into your application by tricking it into loading the
|
||||
to sneak their own code into your application by tricking it into loading the
|
||||
code as a module. However, GIO will never load modules from your home
|
||||
directory except when explicitly asked to do so via an environment variable.
|
||||
|
||||
In most cases, your helper program should be so small that you don't need
|
||||
In most cases, your helper program should be so small that you don’t need
|
||||
GIO, whose APIs are largely designed to support full-blown desktop
|
||||
applications. If you can't resist the convenience of these APIs, here are
|
||||
applications. If you can’t resist the convenience of these APIs, here are
|
||||
some steps you should take:
|
||||
|
||||
- Clear the environment, e.g. using the `clearenv()` function. David Wheeler
|
||||
@ -221,7 +222,7 @@ some steps you should take:
|
||||
GIO. In particular, `PATH` (used to locate binaries), `GIO_EXTRA_MODULES`
|
||||
(used to locate loadable modules) and `DBUS_{SYSTEM,SESSION}_BUS_ADDRESS`
|
||||
(used to locate the D-Bus system and session bus) are important.
|
||||
- Don't use GVfs, by setting `GIO_USE_VFS=local` in the environment. The
|
||||
- Don’t use GVfs, by setting `GIO_USE_VFS=local` in the environment. The
|
||||
reason to avoid GVfs in security-sensitive programs is that it uses many
|
||||
libraries which have not necessarily been audited for security problems.
|
||||
Gvfs is also heavily distributed and relies on a session bus to be
|
||||
@ -231,10 +232,11 @@ some steps you should take:
|
||||
|
||||
GIO comes with a `gio-2.0.pc` file that you should use together with
|
||||
pkg-config to obtain the necessary information about header files and
|
||||
libraries. See the pkg-config man page or the GLib documentation for more
|
||||
libraries. See the [pkg-config man page](man:pkg-config(1)) or the
|
||||
[GLib documentation](https://docs.gtk.org/glib/compiling.html) for more
|
||||
information on how to use pkg-config to compile your application.
|
||||
|
||||
If you are using GIO on UNIX-like systems, you may want to use UNIX-specific
|
||||
If you are using GIO on Unix-like systems, you may want to use Unix-specific
|
||||
GIO interfaces such as `GUnixInputStream`, `GUnixOutputStream`, `GUnixMount`
|
||||
or `GDesktopAppInfo`. To do so, use the `gio-unix-2.0.pc` file as well as
|
||||
`gio-2.0.pc` (or, in GIR namespace terms, `GioUnix-2.0` as well as `Gio-2.0`).
|
||||
@ -253,9 +255,9 @@ GIO inspects a few environment variables in addition to the ones used by GLib.
|
||||
- `GIO_USE_VFS`. This environment variable can be set to the name of a GVfs
|
||||
implementation to override the default for debugging purposes. The GVfs
|
||||
implementation for local files that is included in GIO has the name
|
||||
"local", the implementation in the gvfs module has the name "gvfs". Most
|
||||
commonly, system software will set this to "local" to avoid having `GFile`
|
||||
APIs perform unnecessary D-Bus calls. The special value "help" can be used
|
||||
`local`, the implementation in the GVfs module has the name `gvfs`. Most
|
||||
commonly, system software will set this to `local` to avoid having [iface@Gio.File]
|
||||
APIs perform unnecessary D-Bus calls. The special value `help` can be used
|
||||
to print a list of available implementations to standard output.
|
||||
|
||||
The following environment variables are only useful for debugging GIO itself
|
||||
@ -263,38 +265,38 @@ or modules that it loads. They should not be set in a production
|
||||
environment.
|
||||
|
||||
- `GIO_USE_FILE_MONITOR`. This variable can be set to the name of a
|
||||
GFileMonitor implementation to override the default for debugging
|
||||
purposes. The GFileMonitor implementation for local files that is included
|
||||
in GIO on Linux has the name "inotify", others that are built are built as
|
||||
modules (depending on the platform) are called "fam" and "fen". The
|
||||
special value "help" can be used to print a list of available
|
||||
[class@Gio.FileMonitor] implementation to override the default for debugging
|
||||
purposes. The [class@Gio.FileMonitor] implementation for local files that is included
|
||||
in GIO on Linux has the name `inotify`, others that are built are built as
|
||||
modules (depending on the platform) are called `kqueue` and `win32`. The
|
||||
special value `help` can be used to print a list of available
|
||||
implementations to standard output.
|
||||
- `GIO_USE_VOLUME_MONITOR`. This variable can be set to the name of a
|
||||
GVolumeMonitor implementation to override the default for debugging
|
||||
purposes. The GVolumeMonitor implementation for local files that is
|
||||
included in GIO has the name "unix", the udisks2-based implementation in
|
||||
the gvfs module has the name "udisks2". The special value "help" can be used
|
||||
[class@Gio.VolumeMonitor] implementation to override the default for debugging
|
||||
purposes. The [class@Gio.VolumeMonitor] implementation for local files that is
|
||||
included in GIO has the name `unix`, the udisks2-based implementation in
|
||||
the GVfs module has the name `udisks2`. The special value `help` can be used
|
||||
to print a list of available implementations to standard output.
|
||||
- `GIO_USE_MEMORY_MONITOR`. This variable can be set to the name of a
|
||||
GMemoryMonitory implementation to override the default for debugging
|
||||
[iface@Gio.MemoryMonitor] implementation to override the default for debugging
|
||||
purposes. The available implementations included in GIO have the names
|
||||
"dbus", "portal" and "win32". The special value "help" can be used
|
||||
`dbus`, `portal` and `win32`. The special value `help` can be used
|
||||
to print a list of available implementations to standard output.
|
||||
- `GIO_USE_NETWORK_MONITOR`. This variable can be set to the name of a
|
||||
GNetworkMonitor implementation to override the default for debugging
|
||||
[iface@Gio.NetworkMonitor] implementation to override the default for debugging
|
||||
purposes. The available implementations included in GIO have the names
|
||||
"netlink", "networkmanager" and "portal". The special value "help" can
|
||||
`netlink`, `networkmanager` and `portal`. The special value `help` can
|
||||
be used to print a list of available implementations to standard output.
|
||||
- `GIO_USE_POWER_PROFILE_MONITOR`. This variable can be set to the name of a
|
||||
GPowerProfileMonitor implementation to override the default for debugging
|
||||
[iface@Gio.PowerProfileMonitor] implementation to override the default for debugging
|
||||
purposes. The available implementations included in GIO have the names
|
||||
"dbus" and "portal". The special value "help" can be used to print a list
|
||||
`dbus` and `portal`. The special value `help` can be used to print a list
|
||||
of available implementations to standard output.
|
||||
- `GIO_USE_TLS`. This variable can be set to the name of a GTlsBackend
|
||||
- `GIO_USE_TLS`. This variable can be set to the name of a [iface@Gio.TlsBackend]
|
||||
implementation to override the default for debugging purposes. GIO does
|
||||
not include a GTlsBackend implementation, the gnutls-based implementation
|
||||
in the glib-networking module has the name "gnutls". The special value
|
||||
"help" can be used to print a list of available implementations to standard
|
||||
not include a [iface@Gio.TlsBackend] implementation — the GnuTLS-based implementation
|
||||
in the glib-networking module has the name `gnutls`. The special value
|
||||
`help` can be used to print a list of available implementations to standard
|
||||
output.
|
||||
- `GIO_USE_PORTALS`. This variable can be set to override detection of portals
|
||||
and force them to be used to provide various bits of GIO functionality, for
|
||||
@ -302,26 +304,26 @@ environment.
|
||||
- `GIO_MODULE_DIR`. When this environment variable is set to a path, GIO
|
||||
will load modules from this alternate directory instead of the directory
|
||||
built into GIO. This is useful when running tests, for example. This
|
||||
environment variable is ignored when running in a setuid program.
|
||||
environment variable is ignored when running in a SUID program.
|
||||
- `GIO_EXTRA_MODULES`. When this environment variable is set to a path, or
|
||||
a set of paths separated by a colon, GIO will attempt to load additional
|
||||
modules from within the path. This environment variable is ignored when
|
||||
running in a setuid program.
|
||||
running in a SUID program.
|
||||
- `GNOTIFICATION_BACKEND`. This variable can be set to the name of a
|
||||
GNotificationBackend implementation to override the default for debugging
|
||||
`GNotificationBackend` implementation to override the default for debugging
|
||||
purposes. The implementations that are included in GIO have the names
|
||||
"freedesktop", "cocoa", "gtk" and "portal". The special value "help" can
|
||||
`freedesktop`, `cocoa`, `gtk` and `portal`. The special value `help` can
|
||||
be used to print a list of available implementations to standard output.
|
||||
- `GSETTINGS_BACKEND`. This variable can be set to the name of a
|
||||
GSettingsBackend implementation to override the default for debugging
|
||||
[class@Gio.SettingsBackend] implementation to override the default for debugging
|
||||
purposes. The memory-based implementation that is included in GIO has the
|
||||
name "memory", the one in dconf has the name "dconf". The special value
|
||||
"help" can be used to print a list of available implementations to standard
|
||||
name `memory`, the one in dconf has the name `dconf`. The special value
|
||||
`help` can be used to print a list of available implementations to standard
|
||||
output.
|
||||
- `GSETTINGS_SCHEMA_DIR`. This variable can be set to the names of
|
||||
directories to consider when looking for compiled schemas for GSettings,
|
||||
directories to consider when looking for compiled schemas for [class@Gio.Settings],
|
||||
in addition to the `glib-2.0/schemas` subdirectories of the XDG system
|
||||
data dirs. To specify multiple directories, use `G_SEARCHPATH_SEPARATOR_S`
|
||||
data directories. To specify multiple directories, use `G_SEARCHPATH_SEPARATOR_S`
|
||||
as a separator.
|
||||
- `DBUS_SYSTEM_BUS_ADDRESS`. This variable is consulted to find the address
|
||||
of the D-Bus system bus. For the format of D-Bus addresses, see the
|
||||
@ -332,32 +334,32 @@ environment.
|
||||
address of the D-Bus session bus. Setting this variable overrides
|
||||
platform-specific ways of determining the session bus address.
|
||||
- `DBUS_STARTER_BUS_TYPE`. This variable is consulted to find out the
|
||||
'starter' bus for an application that has been started via D-Bus
|
||||
activation. The possible values are 'system' or 'session'.
|
||||
‘starter’ bus for an application that has been started via D-Bus
|
||||
activation. The possible values are `system` or `session`.
|
||||
- `G_DBUS_DEBUG`. This variable can be set to a list of debug options,
|
||||
which cause GLib to print out different types of debugging information
|
||||
when using the D-Bus routines.
|
||||
- `transport`: Show IO activity (e.g. reads and writes)
|
||||
- `transport`: Show I/O activity (e.g. reads and writes)
|
||||
- `message`: Show all sent and received D-Bus messages
|
||||
- `payload`: Show payload for all sent and received D-Bus messages (implies
|
||||
message)
|
||||
- `call`: Trace `g_dbus_connection_call()` and
|
||||
`g_dbus_connection_call_sync()` API usage
|
||||
- `call`: Trace [method@Gio.DBusConnection.call] and
|
||||
[method@Gio.DBusConnection.call_sync] API usage
|
||||
- `signal`: Show when a D-Bus signal is received
|
||||
- `incoming`: Show when an incoming D-Bus method call is received
|
||||
- `return`: Show when a reply is returned via the GDBusMethodInvocation API
|
||||
- `emission`: Trace `g_dbus_connection_emit_signal()` API usage
|
||||
- `return`: Show when a reply is returned via the [class@Gio.DBusMethodInvocation] API
|
||||
- `emission`: Trace [method@Gio.DBusConnection.emit_signal] API usage
|
||||
- `authentication`: Show information about connection authentication
|
||||
- `address`: Show information about D-Bus address lookups and autolaunching
|
||||
- `all`: Turn on all debug options
|
||||
- `help`: Print a list of supported options to the standard output
|
||||
- `G_DBUS_COOKIE_SHA1_KEYRING_DIR`. Can be used to override the directory
|
||||
used to store the keyring used in the `DBUS_COOKIE_SHA1` authentication
|
||||
mechanism. Normally the directory used is `.dbus-keyrings` in the user's
|
||||
mechanism. Normally the directory used is `.dbus-keyrings` in the user’s
|
||||
home directory.
|
||||
- `G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION`. If set, the
|
||||
permissions of the directory used to store the keyring used in the
|
||||
`DBUS_COOKIE_SHA1` authentication mechanism won't be checked. Normally the
|
||||
`DBUS_COOKIE_SHA1` authentication mechanism won’t be checked. Normally the
|
||||
directory must be readable only by the user.
|
||||
|
||||
## Extending GIO
|
||||
@ -371,77 +373,77 @@ see [`struct@Gio.IOExtensionPoint`].
|
||||
The following extension points are currently defined by GIO:
|
||||
|
||||
- `G_VFS_EXTENSION_POINT_NAME`. Allows to override the functionality of the
|
||||
GVfs class. Implementations of this extension point must be derived from
|
||||
GVfs. GIO uses the implementation with the highest priority that is
|
||||
active, see `g_vfs_is_active()`. GIO implements this extension point for
|
||||
[class@Gio.Vfs] class. Implementations of this extension point must be derived from
|
||||
[class@Gio.Vfs]. GIO uses the implementation with the highest priority that is
|
||||
active, see [method@Gio.Vfs.is_active]. GIO implements this extension point for
|
||||
local files, gvfs contains an implementation that supports all the
|
||||
backends in gvfs.
|
||||
- `G_VOLUME_MONITOR_EXTENSION_POINT_NAME`. Allows to add more volume
|
||||
monitors. Implementations of this extension point must be derived from
|
||||
GVolumeMonitor. GIO uses all registered extensions. gvfs contains an
|
||||
implementation that works together with the GVfs implementation in gvfs.
|
||||
[class@Gio.VolumeMonitor]. GIO uses all registered extensions. gvfs contains an
|
||||
implementation that works together with the [class@Gio.Vfs] implementation in gvfs.
|
||||
- `G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME`. Allows to override the
|
||||
'native' volume monitor. Implementations of this extension point must be
|
||||
derived from GNativeVolumeMonitor. GIO uses the implementation with the
|
||||
highest priority that is supported, as determined by the `is_supported()`
|
||||
vfunc in GVolumeMonitorClass. GIO implements this extension point for
|
||||
‘native’ volume monitor. Implementations of this extension point must be
|
||||
derived from [class@Gio.NativeVolumeMonitor]. GIO uses the implementation with the
|
||||
highest priority that is supported, as determined by
|
||||
`GVolumeMonitorClass.is_supported()`. GIO implements this extension point for
|
||||
local mounts, gvfs contains a udisks2-based implementation.
|
||||
- `G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME`. Allows to override the file
|
||||
monitor implementation for local files. Implementations of this extension
|
||||
point must be derived from GLocalFileMonitor. GIO uses the implementation
|
||||
with the highest priority that is supported, as determined by the
|
||||
`is_supported()` vfunc in GLocalFileMonitorClass. GIO uses this extension
|
||||
point internally, to switch between its fam-based and inotify-based file
|
||||
point must be derived from `GLocalFileMonitor`. GIO uses the implementation
|
||||
with the highest priority that is supported, as determined by
|
||||
`GLocalFileMonitorClass.is_supported()`. GIO uses this extension
|
||||
point internally, to switch between its poll-based and inotify-based file
|
||||
monitoring implementations.
|
||||
- `G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME`. Allows to override the
|
||||
directory monitor implementation for local files. Implementations of this
|
||||
extension point must be derived from GLocalDirectoryMonitor. GIO uses the
|
||||
extension point must be derived from `GLocalDirectoryMonitor`. GIO uses the
|
||||
implementation with the highest priority that is supported, as determined
|
||||
by the `is_supported()` vfunc in GLocalDirectoryMonitorClass. GIO uses
|
||||
this extension point internally, to switch between its fam-based and
|
||||
by `GLocalDirectoryMonitorClass.is_supported()`. GIO uses
|
||||
this extension point internally, to switch between its poll-based and
|
||||
inotify-based directory monitoring implementations.
|
||||
- `G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME`. Unix-only. Allows to
|
||||
provide a way to associate default handlers with URI schemes.
|
||||
Implementations of this extension point must implement the
|
||||
GDesktopAppInfoLookup interface. GIO uses the implementation with the
|
||||
`GDesktopAppInfoLookup` interface. GIO uses the implementation with the
|
||||
highest priority. This extension point has been discontinued in GLib 2.28.
|
||||
It is still available to keep API and ABI stability, but GIO is no longer
|
||||
using it for default handlers. Instead, the mime handler mechanism is
|
||||
used, together with x-scheme-handler pseudo-mimetypes.
|
||||
using it for default handlers. Instead, the MIME handler mechanism is
|
||||
used, together with `x-scheme-handler` pseudo-MIME-types.
|
||||
- `G_NOTIFICATION_BACKEND_EXTENSION_POINT_NAME`. Allows to provide an
|
||||
alternative implementation for sending notifications. Implementations of
|
||||
this extension point must derive from the GNotificationBackend type. GIO
|
||||
this extension point must derive from the `GNotificationBackend` type. GIO
|
||||
contains implementations based on the freedesktop notification D-Bus
|
||||
interface, the macOS Cocoa API, the gnome-shell D-Bus API, and the desktop
|
||||
portal for this functionality.
|
||||
- `G_SETTINGS_BACKEND_EXTENSION_POINT_NAME`. Allows to provide an
|
||||
alternative storage for GSettings. Implementations of this extension point
|
||||
must derive from the GSettingsBackend type. GIO contains a keyfile-based
|
||||
alternative storage for [class@Gio.Settings]. Implementations of this extension point
|
||||
must derive from the [class@Gio.SettingsBackend] type. GIO contains a keyfile-based
|
||||
implementation of this extension point, another one is provided by dconf.
|
||||
- `G_PROXY_EXTENSION_POINT_NAME`. Allows to provide implementations for
|
||||
network proxying. Implementations of this extension point must provide the
|
||||
GProxy interface, and must be named after the network protocol they are
|
||||
[iface@Gio.Proxy] interface, and must be named after the network protocol they are
|
||||
proxying. glib-networking contains an implementation of this extension
|
||||
point based on libproxy.
|
||||
- `G_TLS_BACKEND_EXTENSION_POINT_NAME`. Allows to provide implementations
|
||||
for TLS support. Implementations of this extension point must implement
|
||||
the GTlsBackend interface. glib-networking contains an implementation of
|
||||
the [iface@Gio.TlsBackend] interface. glib-networking contains an implementation of
|
||||
this extension point.
|
||||
- `G_NETWORK_MONITOR_EXTENSION_POINT_NAME`. Allows to provide
|
||||
implementations for network connectivity monitoring. Implementations of
|
||||
this extension point must implement the GNetworkMonitorInterface
|
||||
this extension point must implement the [iface@Gio.NetworkMonitor]
|
||||
interface. GIO contains implementations of this extension point that use
|
||||
the netlink interface of the Linux kernel, the NetworkManager D-Bus interface
|
||||
and the desktop portal for this functionality.
|
||||
- `G_MEMORY_MONITOR_EXTENSION_POINT_NAME`. Allows to provide
|
||||
implementations for memory usage monitoring. Implementations of this
|
||||
extension point must implement the GMemoryMonitorInterface interface.
|
||||
extension point must implement the [iface@Gio.MemoryMonitor] interface.
|
||||
GIO contains implementations of this extension point that use the
|
||||
org.freedesktop.LowMemoryMonitor D-Bus interface, the Windows API and
|
||||
`org.freedesktop.LowMemoryMonitor` D-Bus interface, the Windows API and
|
||||
the desktop portal for this functionality.
|
||||
- `G_POWER_PROFILE_MONITOR_EXTENSION_POINT_NAME`. Allows to provide
|
||||
implementations for power usage monitoring. Implementations of this
|
||||
extension point must implement the GPowerProfileMonitorInterface interface.
|
||||
extension point must implement the [iface@Gio.PowerProfileMonitor] interface.
|
||||
GIO contains implementations of this extension point that use the
|
||||
net.hadess.PowerProfiles D-Bus interface and the desktop portal for
|
||||
`net.hadess.PowerProfiles` D-Bus interface and the desktop portal for
|
||||
this functionality.
|
||||
|
Loading…
x
Reference in New Issue
Block a user