mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-26 07:26:15 +01:00
6ea86cc57f
This imports the network APIs into the gio reference docs, and cleans up a bunch of gtk-doc warnings and documentation issues.
353 lines
13 KiB
XML
353 lines
13 KiB
XML
<part>
|
|
<title>GIO Overview</title>
|
|
|
|
<chapter>
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
GIO is striving to provide a modern, easy-to-use VFS API that sits
|
|
at the right level in the library stack. 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 providing higher-level, document-centric interfaces.
|
|
</para>
|
|
|
|
<para>
|
|
The abstract file system model of GIO consists of a number of
|
|
interfaces and base classes for I/O and files:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>GFile</term>
|
|
<listitem><para>reference to a file</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GFileInfo</term>
|
|
<listitem><para>information about a file or filesystem</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GFileEnumerator</term>
|
|
<listitem><para>list files in directories</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GDrive</term>
|
|
<listitem><para>represents a drive</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GVolume</term>
|
|
<listitem><para>represents a file system in an abstract way</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GMount</term>
|
|
<listitem><para>represents a mounted file system</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
Then there is a number of stream classes, similar to the input and
|
|
output stream hierarchies that can be found in frameworks like Java:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>GInputStream</term>
|
|
<listitem><para>read data</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GOutputStream</term>
|
|
<listitem><para>write data</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GIOStream</term>
|
|
<listitem><para>read and write data</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GSeekable</term>
|
|
<listitem><para>interface optionally implemented by streams to support seeking</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
There are interfaces related to applications and the types
|
|
of files they handle:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>GAppInfo</term>
|
|
<listitem><para>information about an installed application</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GIcon</term>
|
|
<listitem><para>abstract type for file and application icons</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
There is support for network programming, including name resolution, lowlevel socket
|
|
APIs and highlevel client and server helper classes:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>GSocket</term>
|
|
<listitem><para>lowlevel platform independent socket object</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GResolver</term>
|
|
<listitem><para>asynchronous and cancellable DNS resolver</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GSocketClient</term>
|
|
<listitem><para>high-level network client helper</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GSocketService</term>
|
|
<listitem><para>high-level network server helper</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>GSocketConnection</term>
|
|
<listitem><para>network connection stream</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
Beyond these, GIO provides facilities for file monitoring,
|
|
asynchronous I/O and filename completion. In addition to the
|
|
interfaces, GIO provides implementations for the local case.
|
|
Implementations for various network file systems are provided
|
|
by the GVFS package as loadable modules.
|
|
</para>
|
|
|
|
<para>
|
|
Other design choices which consciously break with the GnomeVFS
|
|
design are to move backends out-of-process, which minimizes the
|
|
dependency bloat and makes the whole system more robust. The backends
|
|
are not included in GIO, but in the separate GVFS package. The GVFS
|
|
package also contains the GVFS daemon, which spawn further mount
|
|
daemons for each individual connection.
|
|
</para>
|
|
|
|
<figure id="gvfs-overview">
|
|
<title>GIO in the GTK+ library stack</title>
|
|
<graphic fileref="gvfs-overview.png" format="PNG"></graphic>
|
|
</figure>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Compiling GIO applications</title>
|
|
|
|
<para>
|
|
GIO comes with a <filename>gio-2.0.pc</filename> file that you
|
|
should use together with <literal>pkg-config</literal> to obtain
|
|
the necessary information about header files and libraries. See
|
|
the <literal>pkg-config</literal> man page or the GLib documentation
|
|
for more information on how to use <literal>pkg-config</literal>
|
|
to compile your application.
|
|
</para>
|
|
|
|
<para>
|
|
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 <filename>gio-unix-2.0.pc</filename> file
|
|
instead of <filename>gio-2.0.pc</filename>
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter>
|
|
<title>Running GIO applications</title>
|
|
|
|
<para>
|
|
GIO inspects a few of environment variables in addition to the
|
|
ones used by GLib.
|
|
</para>
|
|
|
|
<formalpara>
|
|
<title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
|
|
|
|
<para>
|
|
GIO uses these environment variables to locate MIME information.
|
|
For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
|
|
and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GVFS_DISABLE_FUSE</envar></title>
|
|
|
|
<para>
|
|
This variable can be set to keep #Gvfs from starting the fuse backend,
|
|
which may be unwanted or unnecessary in certain situations.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<para>
|
|
The following environment variables are only useful for debugging
|
|
GIO itself or modules that it loads. They should not be set in a
|
|
production environment.
|
|
</para>
|
|
<formalpara>
|
|
<title><envar>GIO_USE_VFS</envar></title>
|
|
|
|
<para>
|
|
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".
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
|
|
|
|
<para>
|
|
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 hal-based implementation in the
|
|
gvfs module has the name "hal".
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GIO_USE_URI_ASSOCIATION</envar></title>
|
|
|
|
<para>
|
|
This variable can be set to the name of a #GDesktopAppInfoLookup
|
|
implementation to override the default for debugging purposes.
|
|
GIO does not include a #GDesktopAppInfoLookup implementation,
|
|
the GConf-based implementation in the gvfs module has the name
|
|
"gconf".
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GVFS_INOTIFY_DIAG</envar></title>
|
|
|
|
<para>
|
|
When this environment variable is set and GIO has been built
|
|
with inotify support, a dump of diagnostic inotify information
|
|
will be written every 20 seconds to a file named
|
|
<filename>/tmp/gvfsdid.<replaceable>pid</replaceable></filename>.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title><envar>GIO_EXTRA_MODULES</envar></title>
|
|
|
|
<para>
|
|
When this environment variable is set to a path, or a set of
|
|
paths separated by a colon, GIO will attempt to load
|
|
modules from within the path.
|
|
</para>
|
|
</formalpara>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="extending-gio">
|
|
<title>Extending GIO</title>
|
|
|
|
<para>
|
|
A lot of the functionality that is accessible through GIO
|
|
is implemented in loadable modules, and modules provide a convenient
|
|
way to extend GIO. In addition to the #GIOModule API which supports
|
|
writing such modules, GIO has a mechanism to define extension points,
|
|
and register implementations thereof, see #GIOExtensionPoint.
|
|
</para>
|
|
<para>
|
|
The following extension points are currently defined by GIO:
|
|
</para>
|
|
|
|
<formalpara>
|
|
<title>G_VFS_EXTENSION_POINT_NAME</title>
|
|
|
|
<para>
|
|
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().
|
|
</para>
|
|
<para>
|
|
GIO implements this extension point for local files, gvfs contains
|
|
an implementation that supports all the backends in gvfs.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
|
|
|
|
<para>
|
|
Allows to add more volume monitors.
|
|
Implementations of this extension point must be derived from
|
|
#GVolumeMonitor. GIO uses all registered extensions.
|
|
</para>
|
|
<para>
|
|
gvfs contains an implementation that works together with the #GVfs
|
|
implementation in gvfs.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
GIO implements this extension point for local mounts,
|
|
gvfs contains a hal-based implementation.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
GIO uses this extension point internally, to switch between
|
|
its fam-based and inotify-based file monitoring implementations.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title>G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME</title>
|
|
|
|
<para>
|
|
Allows to override the directory monitor implementation for
|
|
local files. Implementations of this 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.
|
|
</para>
|
|
<para>
|
|
GIO uses this extension point internally, to switch between
|
|
its fam-based and inotify-based directory monitoring implementations.
|
|
</para>
|
|
</formalpara>
|
|
|
|
<formalpara>
|
|
<title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
|
|
|
|
<para>
|
|
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 highest priority.
|
|
</para>
|
|
<para>
|
|
gvfs contains a GConf-based implementation that uses the
|
|
same GConf keys as gnome-vfs.
|
|
</para>
|
|
</formalpara>
|
|
</chapter>
|
|
</part>
|