docs/reference/gio/overview.xml

   1 <part>
   2   <title>GIO Overview</title>
   3
   4   <chapter>
   5     <title>Introduction</title>
   6
   7   <para>
   8     GIO is striving to provide a modern, easy-to-use VFS API that sits
   9     at the right level in the library stack. The goal is to overcome the
  10     shortcomings of GnomeVFS and provide an API that is so good that
  11     developers prefer it over raw POSIX calls. Among other things
  12     that means using GObject. It also means not cloning the POSIX
  13     API, but providing higher-level, document-centric interfaces.
  14   </para>
  15
  16   <para>
  17     The abstract file system model of GIO consists of a number of
  18     interfaces and base classes for I/O and files:
  19     <variablelist>
  20        <varlistentry>
  21          <term>GFile</term>
  22          <listitem><para>reference to a file</para></listitem>
  23        </varlistentry>
  24        <varlistentry>
  25          <term>GFileInfo</term>
  26          <listitem><para>information about a file or filesystem</para></listitem>
  27        </varlistentry>
  28        <varlistentry>
  29          <term>GFileEnumerator</term>
  30          <listitem><para>list files in directories</para></listitem>
  31        </varlistentry>
  32        <varlistentry>
  33          <term>GDrive</term>
  34          <listitem><para>represents a drive</para></listitem>
  35        </varlistentry>
  36        <varlistentry>
  37          <term>GVolume</term>
  38          <listitem><para>represents a file system in an abstract way</para></listitem>
  39        </varlistentry>
  40        <varlistentry>
  41          <term>GMount</term>
  42          <listitem><para>represents a mounted file system</para></listitem>
  43        </varlistentry>
  44     </variablelist>
  45     Then there is a number of stream classes, similar to the input and
  46     output stream hierarchies that can be found in frameworks like Java:
  47     <variablelist>
  48        <varlistentry>
  49          <term>GInputStream</term>
  50          <listitem><para>read data</para></listitem>
  51        </varlistentry>
  52        <varlistentry>
  53          <term>GOutputStream</term>
  54          <listitem><para>write data</para></listitem>
  55        </varlistentry>
  56        <varlistentry>
  57          <term>GSeekable</term>
  58          <listitem><para>interface optionally implemented by streams to support seeking</para></listitem>
  59        </varlistentry>
  60     </variablelist>
  61     There are interfaces related to applications and the types
  62     of files they handle:
  63     <variablelist>
  64        <varlistentry>
  65           <term>GAppInfo</term>
  66           <listitem><para>information about an installed application</para></listitem>
  67        </varlistentry>
  68        <varlistentry>
  69           <term>GIcon</term>
  70           <listitem><para>abstract type for file and application icons</para></listitem>
  71        </varlistentry>
  72     </variablelist>
  73     Beyond these, GIO provides facilities for file monitoring,
  74     asynchronous I/O and filename completion. In addition to the
  75     interfaces, GIO provides implementations for the local case.
  76     Implementations for various network file systems are provided
  77     by the GVFS package as loadable modules.
  78   </para>
  79
  80   <para>
  81     Other design choices which consciously break with the GnomeVFS
  82     design are to move backends out-of-process, which minimizes the
  83     dependency bloat and makes the whole system more robust. The backends
  84     are not included in GIO, but in the separate GVFS package. The GVFS
  85     package also contains the GVFS daemon, which spawn further mount
  86     daemons for each individual connection.
  87   </para>
  88
  89   <figure id="gvfs-overview">
  90     <title>GIO in the GTK+ library stack</title>
  91     <graphic fileref="gvfs-overview.png" format="PNG"></graphic>
  92   </figure>
  93
  94   <para>
  95     The GIO model of I/O is stateful: if an application establishes e.g.
  96     a SFTP connection to a server, it becomes available to all applications
  97     in the session; the user does not have to enter his password over
  98     and over again.
  99   </para>
 100   <para>
 101     One of the big advantages of putting the VFS in the GLib layer
 102     is that GTK+ can directly use it, e.g. in the filechooser.
 103   </para>
 104   </chapter>
 105
 106   <chapter>
 107     <title>Compiling GIO applications</title>
 108
 109     <para>
 110       GIO comes with a <filename>gio-2.0.pc</filename> file that you
 111       should use together with <literal>pkg-config</literal> to obtain
 112       the necessary information about header files and libraries. See
 113       the <literal>pkg-config</literal> man page or the GLib documentation
 114       for more information on how to use <literal>pkg-config</literal>
 115       to compile your application.
 116     </para>
 117
 118     <para>
 119       If you are using GIO on UNIX-like systems, you may want to use
 120       UNIX-specific GIO interfaces such as #GUnixInputStream,
 121       #GUnixOutputStream, #GUnixMount or #GDesktopAppInfo.
 122       To do so, use the <filename>gio-unix-2.0.pc</filename> file
 123       instead of <filename>gio-2.0.pc</filename>
 124     </para>
 125   </chapter>
 126
 127   <chapter>
 128     <title>Running GIO applications</title>
 129
 130     <para>
 131       GIO inspects a few of environment variables in addition to the
 132       ones used by GLib.
 133     </para>
 134
 135     <formalpara>
 136       <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
 137
 138       <para>
 139         GIO uses these environment variables to locate MIME information.
 140         For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
 141         and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
 142       </para>
 143     </formalpara>
 144
 145     <formalpara>
 146       <title><envar>GVFS_DISABLE_FUSE</envar></title>
 147
 148       <para>
 149         This variable can be set to keep #Gvfs from starting the fuse backend,
 150         which may be unwanted or unnecessary in certain situations.
 151       </para>
 152     </formalpara>
 153
 154     <para>
 155       The following environment variables are only useful for debugging
 156       GIO itself or modules that it loads. They should not be set in a
 157       production environment.
 158     </para>
 159     <formalpara>
 160       <title><envar>GIO_USE_VFS</envar></title>
 161
 162       <para>
 163         This environment variable can be set to the name of a #GVfs
 164         implementation to override the default for debugging purposes.
 165         The #GVfs implementation for local files that is included in GIO
 166         has the name "local", the implementation in the gvfs module has
 167         the name "gvfs".
 168       </para>
 169     </formalpara>
 170
 171     <formalpara>
 172       <title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
 173
 174       <para>
 175         This variable can be set to the name of a #GVolumeMonitor
 176         implementation to override the default for debugging purposes.
 177         The #GVolumeMonitor implementation for local files that is included
 178         in GIO has the name "unix", the hal-based implementation in the
 179         gvfs module has the name "hal".
 180       </para>
 181     </formalpara>
 182
 183     <formalpara>
 184       <title><envar>GIO_USE_URI_ASSOCIATION</envar></title>
 185
 186       <para>
 187         This variable can be set to the name of a #GDesktopAppInfoLookup
 188         implementation to override the dfeault for debugging purposes.
 189         GIO does not include a #GDesktopAppInfoLookup implementation,
 190         the GConf-based implementation in the gvfs module has the name
 191         "gconf".
 192       </para>
 193     </formalpara>
 194
 195     <formalpara>
 196       <title><envar>GVFS_INOTIFY_DIAG</envar></title>
 197
 198       <para>
 199         When this environment variable is set and GIO has been built
 200         with inotify support, a dump of diagnostic inotify information
 201         will be written every 20 seconds to a file named
 202         <filename>/tmp/gvfsdid.<replaceable>pid</replaceable></filename>.
 203       </para>
 204     </formalpara>
 205
 206   </chapter>
 207
 208   <chapter id="gio-extension-points">
 209     <title>Extending GIO</title>
 210
 211     <para>
 212       A lot of the functionality that is accessible through GIO
 213       is implemented in loadable modules, and modules provide a convenient
 214       way to extend GIO. In addition to the #GIOModule API which supports
 215       writing such modules, GIO has a mechanism to define extension points,
 216       and register implementations thereof, see #GIOExtensionPoint.
 217     </para>
 218     <para>
 219       The following extension points are currently defined by GIO:
 220     </para>
 221
 222     <formalpara>
 223        <title>G_VFS_EXTENSION_POINT_NAME</title>
 224
 225        <para>
 226           Allows to override the functionality of the #GVfs class.
 227           Implementations of this extension point must be derived from #GVfs.
 228           GIO uses the implementation with the highest priority that is active,
 229           see g_vfs_is_active().
 230        </para>
 231        <para>
 232           GIO implements this extension point for local files, gvfs contains
 233           an implementation that supports all the backends in gvfs.
 234        </para>
 235    </formalpara>
 236
 237    <formalpara>
 238       <title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 239
 240       <para>
 241          Allows to add more volume monitors.
 242          Implementations of this extension point must be derived from
 243          #GVolumeMonitor. GIO uses all registered extensions.
 244       </para>
 245       <para>
 246         gvfs contains an implementation that works together with the #GVfs
 247         implementation in gvfs.
 248       </para>
 249    </formalpara>
 250
 251    <formalpara>
 252       <title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 253
 254       <para>
 255          Allows to override the 'native' volume monitor.
 256          Implementations of this extension point must be derived from
 257          #GNativeVolumeMonitor. GIO uses the implementation with
 258          the highest priority that is supported, as determined by the
 259          is_supported() vfunc in #GVolumeMonitorClass.
 260       </para>
 261       <para>
 262          GIO implements this extension point for local mounts,
 263          gvfs contains a hal-based implementation.
 264       </para>
 265    </formalpara>
 266
 267    <formalpara>
 268       <title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
 269
 270       <para>
 271         Allows to override the file monitor implementation for
 272         local files. Implementations of this extension point must
 273         be derived from #GLocalFileMonitor. GIO uses the implementation
 274         with the highest priority that is supported, as determined by the
 275         is_supported() vfunc in #GLocalFileMonitorClass.
 276       </para>
 277       <para>
 278         GIO uses this extension point internally, to switch between
 279         its fam-based and inotify-based file monitoring implementations.
 280       </para>
 281    </formalpara>
 282
 283    <formalpara>
 284       <title>G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME</title>
 285
 286       <para>
 287         Allows to override the directory monitor implementation for
 288         local files. Implementations of this extension point must be
 289         derived from #GLocalDirectoryMonitor. GIO uses the implementation
 290         with the highest priority that is supported, as determined by the
 291         is_supported() vfunc in #GLocalDirectoryMonitorClass.
 292       </para>
 293       <para>
 294         GIO uses this extension point internally, to switch between
 295         its fam-based and inotify-based directory monitoring implementations.
 296       </para>
 297    </formalpara>
 298
 299    <formalpara>
 300       <title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
 301
 302       <para>
 303         Unix-only. Allows to provide a way to associate default handlers
 304         with URI schemes. Implementations of this extension point must
 305         implement the #GDesktopAppInfoLookup interface. GIO uses the
 306         implementation with the highest priority.
 307       </para>
 308       <para>
 309         gvfs contains a GConf-based implementation that uses the
 310         same GConf keys as gnome-vfs.
 311       </para>
 312    </formalpara>
 313   </chapter>
 314 </part>