glib/docs/reference/gio/overview.xml
A. Walton 096201834d Adds GIO_EXTRA_MODULES environment variable support, closing bug #523039.
2008-03-28  A. Walton  <awalton@svn.gnome.org>

	* giomodule.c (_g_io_modules_ensure_loaded):
	Adds GIO_EXTRA_MODULES environment variable support, closing bug 
	#523039.


svn path=/trunk/; revision=6768
2008-03-28 14:31:09 +00:00

325 lines
12 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>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>
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="gio-extension-points">
<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>