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>GIOStream</term>
  58          <listitem><para>read and write data</para></listitem>
  59        </varlistentry>
  60        <varlistentry>
  61          <term>GSeekable</term>
  62          <listitem><para>interface optionally implemented by streams to support seeking</para></listitem>
  63        </varlistentry>
  64     </variablelist>
  65     There are interfaces related to applications and the types
  66     of files they handle:
  67     <variablelist>
  68        <varlistentry>
  69           <term>GAppInfo</term>
  70           <listitem><para>information about an installed application</para></listitem>
  71        </varlistentry>
  72        <varlistentry>
  73           <term>GIcon</term>
  74           <listitem><para>abstract type for file and application icons</para></listitem>
  75        </varlistentry>
  76     </variablelist>
  77     There is a framework for storing and retrieving application settings:
  78     <variablelist>
  79        <varlistentry>
  80           <term>GSettings</term>
  81           <listitem><para>stores and retrieves application settings</para></listitem>
  82        </varlistentry>
  83     </variablelist>
  84     There is support for network programming, including name resolution, lowlevel socket
  85     APIs and highlevel client and server helper classes:
  86     <variablelist>
  87        <varlistentry>
  88           <term>GSocket</term>
  89           <listitem><para>lowlevel platform independent socket object</para></listitem>
  90        </varlistentry>
  91        <varlistentry>
  92           <term>GResolver</term>
  93           <listitem><para>asynchronous and cancellable DNS resolver</para></listitem>
  94        </varlistentry>
  95        <varlistentry>
  96           <term>GSocketClient</term>
  97           <listitem><para>high-level network client helper</para></listitem>
  98        </varlistentry>
  99        <varlistentry>
 100           <term>GSocketService</term>
 101           <listitem><para>high-level network server helper</para></listitem>
 102        </varlistentry>
 103        <varlistentry>
 104           <term>GSocketConnection</term>
 105           <listitem><para>network connection stream</para></listitem>
 106        </varlistentry>
 107     </variablelist>
 108     There is support for connecting to <link linkend="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</link>,
 109     sending and receiving messages, owning and watching bus names,
 110     and making objects available on the bus:
 111     <variablelist>
 112        <varlistentry>
 113           <term>GDBusConnection</term>
 114           <listitem><para>a D-Bus connection</para></listitem>
 115        </varlistentry>
 116
 117        <varlistentry>
 118           <term>GDBusMethodInvocation</term>
 119           <listitem><para>for handling remove calls</para></listitem>
 120        </varlistentry>
 121
 122        <varlistentry>
 123           <term>GDBusServer</term>
 124           <listitem><para>helper for accepting connections</para></listitem>
 125        </varlistentry>
 126
 127        <varlistentry>
 128           <term>GDBusProxy</term>
 129           <listitem><para>proxy to access D-Bus interfaces on a remote object</para></listitem>
 130        </varlistentry>
 131
 132     </variablelist>
 133     Beyond these, GIO provides facilities for file monitoring,
 134     asynchronous I/O and filename completion. In addition to the
 135     interfaces, GIO provides implementations for the local case.
 136     Implementations for various network file systems are provided
 137     by the GVFS package as loadable modules.
 138   </para>
 139
 140   <para>
 141     Other design choices which consciously break with the GnomeVFS
 142     design are to move backends out-of-process, which minimizes the
 143     dependency bloat and makes the whole system more robust. The backends
 144     are not included in GIO, but in the separate GVFS package. The GVFS
 145     package also contains the GVFS daemon, which spawn further mount
 146     daemons for each individual connection.
 147   </para>
 148
 149   <figure id="gvfs-overview">
 150     <title>GIO in the GTK+ library stack</title>
 151     <graphic fileref="gvfs-overview.png" format="PNG"></graphic>
 152   </figure>
 153
 154   <para>
 155     The GIO model of I/O is stateful: if an application establishes e.g.
 156     a SFTP connection to a server, it becomes available to all applications
 157     in the session; the user does not have to enter his password over
 158     and over again.
 159   </para>
 160   <para>
 161     One of the big advantages of putting the VFS in the GLib layer
 162     is that GTK+ can directly use it, e.g. in the filechooser.
 163   </para>
 164   </chapter>
 165
 166   <chapter>
 167     <title>Compiling GIO applications</title>
 168
 169     <para>
 170       GIO comes with a <filename>gio-2.0.pc</filename> file that you
 171       should use together with <literal>pkg-config</literal> to obtain
 172       the necessary information about header files and libraries. See
 173       the <literal>pkg-config</literal> man page or the GLib documentation
 174       for more information on how to use <literal>pkg-config</literal>
 175       to compile your application.
 176     </para>
 177
 178     <para>
 179       If you are using GIO on UNIX-like systems, you may want to use
 180       UNIX-specific GIO interfaces such as #GUnixInputStream,
 181       #GUnixOutputStream, #GUnixMount or #GDesktopAppInfo.
 182       To do so, use the <filename>gio-unix-2.0.pc</filename> file
 183       instead of <filename>gio-2.0.pc</filename>
 184     </para>
 185   </chapter>
 186
 187   <chapter>
 188     <title>Running GIO applications</title>
 189
 190     <para>
 191       GIO inspects a few of environment variables in addition to the
 192       ones used by GLib.
 193     </para>
 194
 195     <formalpara>
 196       <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
 197
 198       <para>
 199         GIO uses these environment variables to locate MIME information.
 200         For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
 201         and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
 202       </para>
 203     </formalpara>
 204
 205     <formalpara>
 206       <title><envar>GVFS_DISABLE_FUSE</envar></title>
 207
 208       <para>
 209         This variable can be set to keep #Gvfs from starting the fuse backend,
 210         which may be unwanted or unnecessary in certain situations.
 211       </para>
 212     </formalpara>
 213
 214     <para>
 215       The following environment variables are only useful for debugging
 216       GIO itself or modules that it loads. They should not be set in a
 217       production environment.
 218     </para>
 219     <formalpara>
 220       <title><envar>GIO_USE_VFS</envar></title>
 221
 222       <para>
 223         This environment variable can be set to the name of a #GVfs
 224         implementation to override the default for debugging purposes.
 225         The #GVfs implementation for local files that is included in GIO
 226         has the name "local", the implementation in the gvfs module has
 227         the name "gvfs".
 228       </para>
 229     </formalpara>
 230
 231     <formalpara>
 232       <title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
 233
 234       <para>
 235         This variable can be set to the name of a #GVolumeMonitor
 236         implementation to override the default for debugging purposes.
 237         The #GVolumeMonitor implementation for local files that is included
 238         in GIO has the name "unix", the hal-based implementation in the
 239         gvfs module has the name "hal".
 240       </para>
 241     </formalpara>
 242
 243     <formalpara>
 244       <title><envar>GIO_USE_URI_ASSOCIATION</envar></title>
 245
 246       <para>
 247         This variable can be set to the name of a #GDesktopAppInfoLookup
 248         implementation to override the default for debugging purposes.
 249         GIO does not include a #GDesktopAppInfoLookup implementation,
 250         the GConf-based implementation in the gvfs module has the name
 251         "gconf".
 252       </para>
 253     </formalpara>
 254
 255     <formalpara>
 256       <title><envar>GVFS_INOTIFY_DIAG</envar></title>
 257
 258       <para>
 259         When this environment variable is set and GIO has been built
 260         with inotify support, a dump of diagnostic inotify information
 261         will be written every 20 seconds to a file named
 262         <filename>/tmp/gvfsdid.<replaceable>pid</replaceable></filename>.
 263       </para>
 264     </formalpara>
 265
 266     <formalpara>
 267       <title><envar>GIO_EXTRA_MODULES</envar></title>
 268
 269       <para>
 270         When this environment variable is set to a path, or a set of
 271         paths separated by a colon, GIO will attempt to load
 272         modules from within the path.
 273       </para>
 274     </formalpara>
 275
 276     <formalpara>
 277       <title><envar>GSETTINGS_BACKEND</envar></title>
 278
 279       <para>
 280         This variable can be set to the name of a #GSettingsBackend
 281         implementation to override the default for debugging purposes.
 282         The memory-based implementation that is included in GIO has
 283         the name "memory", the one in dconf has the name "dconf-settings".
 284       </para>
 285     </formalpara>
 286
 287     <formalpara>
 288       <title><envar>GSETTINGS_SCHEMA_DIR</envar></title>
 289
 290       <para>
 291         This variable can be set to the name of a directory that is
 292         considered in addition to the <filename>glib-2.0/schemas</filename>
 293         subdirectories of the XDG system data dirs when looking
 294         for compiled schemas for #GSettings.
 295       </para>
 296     </formalpara>
 297
 298    <formalpara>
 299       <title><envar>DBUS_SYSTEM_ADDRESS</envar></title>
 300
 301       <para>
 302         This variable is consulted to find the address of the D-Bus system
 303         bus. For the format of D-Bus addresses, see the D-Bus
 304         <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">specification</ulink>.
 305       </para>
 306    </formalpara>
 307
 308    <formalpara>
 309       <title><envar>DBUS_SESSION_ADDRESS</envar></title>
 310
 311       <para>
 312         This variable is consulted to find the address of the D-Bus session bus.
 313       </para>
 314    </formalpara>
 315
 316    <formalpara>
 317       <title><envar>DBUS_STARTER_BUS_TYPE</envar></title>
 318
 319       <para>
 320         This variable is consulted to find out the 'starter' bus for an
 321         application that has been started via D-Bus activation. The possible
 322         values are 'system' or 'session'.
 323       </para>
 324    </formalpara>
 325
 326    <formalpara>
 327       <title><envar>G_DBUS_DEBUG</envar></title>
 328
 329       <para>
 330          This variable can be set to a list of debug options, which
 331          cause GLib to print out different types of debugging
 332          information when using the D-Bus routines.
 333          <variablelist>
 334            <varlistentry>
 335              <term>message</term>
 336              <listitem><para>Show all sent and received D-Bus messages</para></listitem>
 337            </varlistentry>
 338            <varlistentry>
 339              <term>authentication</term>
 340              <listitem><para>Information about authentication</para></listitem>
 341            </varlistentry>
 342          </variablelist>
 343          The special value <literal>all</literal> can be used to turn on
 344          all debug options.
 345       </para>
 346    </formalpara>
 347
 348    <formalpara>
 349       <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR</envar></title>
 350
 351       <para>
 352         Can be used to override the directory used to store the
 353         keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
 354         authentication mechanism. Normally the directory used is
 355         <filename>.dbus-keyrings</filename> in the user's home
 356         directory.
 357       </para>
 358    </formalpara>
 359
 360    <formalpara>
 361       <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION</envar></title>
 362
 363       <para>
 364         If set, the permissions of the directory used to store the
 365         keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
 366         authentication mechanism won't be checked. Normally the
 367         directory must be readable only by the user.
 368       </para>
 369    </formalpara>
 370   </chapter>
 371
 372   <chapter id="extending-gio">
 373     <title>Extending GIO</title>
 374
 375     <para>
 376       A lot of the functionality that is accessible through GIO
 377       is implemented in loadable modules, and modules provide a convenient
 378       way to extend GIO. In addition to the #GIOModule API which supports
 379       writing such modules, GIO has a mechanism to define extension points,
 380       and register implementations thereof, see #GIOExtensionPoint.
 381     </para>
 382     <para>
 383       The following extension points are currently defined by GIO:
 384     </para>
 385
 386     <formalpara>
 387        <title>G_VFS_EXTENSION_POINT_NAME</title>
 388
 389        <para>
 390           Allows to override the functionality of the #GVfs class.
 391           Implementations of this extension point must be derived from #GVfs.
 392           GIO uses the implementation with the highest priority that is active,
 393           see g_vfs_is_active().
 394        </para>
 395        <para>
 396           GIO implements this extension point for local files, gvfs contains
 397           an implementation that supports all the backends in gvfs.
 398        </para>
 399    </formalpara>
 400
 401    <formalpara>
 402       <title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 403
 404       <para>
 405          Allows to add more volume monitors.
 406          Implementations of this extension point must be derived from
 407          #GVolumeMonitor. GIO uses all registered extensions.
 408       </para>
 409       <para>
 410         gvfs contains an implementation that works together with the #GVfs
 411         implementation in gvfs.
 412       </para>
 413    </formalpara>
 414
 415    <formalpara>
 416       <title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 417
 418       <para>
 419          Allows to override the 'native' volume monitor.
 420          Implementations of this extension point must be derived from
 421          #GNativeVolumeMonitor. GIO uses the implementation with
 422          the highest priority that is supported, as determined by the
 423          is_supported() vfunc in #GVolumeMonitorClass.
 424       </para>
 425       <para>
 426          GIO implements this extension point for local mounts,
 427          gvfs contains a hal-based implementation.
 428       </para>
 429    </formalpara>
 430
 431    <formalpara>
 432       <title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
 433
 434       <para>
 435         Allows to override the file monitor implementation for
 436         local files. Implementations of this extension point must
 437         be derived from #GLocalFileMonitor. GIO uses the implementation
 438         with the highest priority that is supported, as determined by the
 439         is_supported() vfunc in #GLocalFileMonitorClass.
 440       </para>
 441       <para>
 442         GIO uses this extension point internally, to switch between
 443         its fam-based and inotify-based file monitoring implementations.
 444       </para>
 445    </formalpara>
 446
 447    <formalpara>
 448       <title>G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME</title>
 449
 450       <para>
 451         Allows to override the directory monitor implementation for
 452         local files. Implementations of this extension point must be
 453         derived from #GLocalDirectoryMonitor. GIO uses the implementation
 454         with the highest priority that is supported, as determined by the
 455         is_supported() vfunc in #GLocalDirectoryMonitorClass.
 456       </para>
 457       <para>
 458         GIO uses this extension point internally, to switch between
 459         its fam-based and inotify-based directory monitoring implementations.
 460       </para>
 461    </formalpara>
 462
 463    <formalpara>
 464       <title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
 465
 466       <para>
 467         Unix-only. Allows to provide a way to associate default handlers
 468         with URI schemes. Implementations of this extension point must
 469         implement the #GDesktopAppInfoLookup interface. GIO uses the
 470         implementation with the highest priority.
 471       </para>
 472       <para>
 473         gvfs contains a GConf-based implementation that uses the
 474         same GConf keys as gnome-vfs.
 475       </para>
 476    </formalpara>
 477
 478    <formalpara>
 479       <title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
 480
 481       <para>
 482         Allows to provide an alternative storage for #GSettings.
 483         Implementations of this extension point must derive from the
 484         #GSettingsBackend type. GIO contains a keyfile-based
 485         implementation of this extension point, another one is provided
 486         by dconf.
 487       </para>
 488    </formalpara>
 489   </chapter>
 490 </part>