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_BUS_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       <para>
 307         Setting this variable overrides platform-specific ways of determining
 308         the system bus address.
 309       </para>
 310    </formalpara>
 311
 312    <formalpara>
 313       <title><envar>DBUS_SESSION_BUS_ADDRESS</envar></title>
 314
 315       <para>
 316         This variable is consulted to find the address of the D-Bus session bus.
 317       </para>
 318       <para>
 319         Setting this variable overrides platform-specific ways of determining
 320         the session bus address.
 321       </para>
 322    </formalpara>
 323
 324    <formalpara>
 325       <title><envar>DBUS_STARTER_BUS_TYPE</envar></title>
 326
 327       <para>
 328         This variable is consulted to find out the 'starter' bus for an
 329         application that has been started via D-Bus activation. The possible
 330         values are 'system' or 'session'.
 331       </para>
 332    </formalpara>
 333
 334    <formalpara>
 335       <title><envar>G_DBUS_DEBUG</envar></title>
 336
 337       <para>
 338          This variable can be set to a list of debug options, which
 339          cause GLib to print out different types of debugging
 340          information when using the D-Bus routines.
 341          <variablelist>
 342            <varlistentry>
 343              <term>message</term>
 344              <listitem><para>Show all sent and received D-Bus messages</para></listitem>
 345            </varlistentry>
 346            <varlistentry>
 347              <term>payload</term>
 348              <listitem><para>Show payload for all sent and received D-Bus messages (implies message)</para></listitem>
 349            </varlistentry>
 350            <varlistentry>
 351              <term>call</term>
 352              <listitem><para>Trace g_dbus_connection_call() and g_dbus_connection_call_sync() API usage</para></listitem>
 353            </varlistentry>
 354            <varlistentry>
 355              <term>signal</term>
 356              <listitem><para>Show when a D-Bus signal is received</para></listitem>
 357            </varlistentry>
 358            <varlistentry>
 359              <term>incoming</term>
 360              <listitem><para>Show when an incoming D-Bus method call is received</para></listitem>
 361            </varlistentry>
 362            <varlistentry>
 363              <term>return</term>
 364              <listitem><para>Show when a reply is returned via the #GDBusMethodInvocation API</para></listitem>
 365            </varlistentry>
 366            <varlistentry>
 367              <term>emission</term>
 368              <listitem><para>Trace g_dbus_connection_emit_signal() API usage</para></listitem>
 369            </varlistentry>
 370            <varlistentry>
 371              <term>authentication</term>
 372              <listitem><para>Show information about connection authentication</para></listitem>
 373            </varlistentry>
 374            <varlistentry>
 375              <term>address</term>
 376              <listitem><para>Show information about D-Bus address lookups and autolaunching</para></listitem>
 377            </varlistentry>
 378          </variablelist>
 379          The special value <literal>all</literal> can be used to turn
 380          on all debug options. The special value
 381          <literal>help</literal> can be used to print a list of
 382          supported options to standard output.
 383       </para>
 384    </formalpara>
 385
 386    <formalpara>
 387       <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR</envar></title>
 388
 389       <para>
 390         Can be used to override the directory used to store the
 391         keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
 392         authentication mechanism. Normally the directory used is
 393         <filename>.dbus-keyrings</filename> in the user's home
 394         directory.
 395       </para>
 396    </formalpara>
 397
 398    <formalpara>
 399       <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION</envar></title>
 400
 401       <para>
 402         If set, the permissions of the directory used to store the
 403         keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
 404         authentication mechanism won't be checked. Normally the
 405         directory must be readable only by the user.
 406       </para>
 407    </formalpara>
 408   </chapter>
 409
 410   <chapter id="extending-gio">
 411     <title>Extending GIO</title>
 412
 413     <para>
 414       A lot of the functionality that is accessible through GIO
 415       is implemented in loadable modules, and modules provide a convenient
 416       way to extend GIO. In addition to the #GIOModule API which supports
 417       writing such modules, GIO has a mechanism to define extension points,
 418       and register implementations thereof, see #GIOExtensionPoint.
 419     </para>
 420     <para>
 421       The following extension points are currently defined by GIO:
 422     </para>
 423
 424     <formalpara>
 425        <title>G_VFS_EXTENSION_POINT_NAME</title>
 426
 427        <para>
 428           Allows to override the functionality of the #GVfs class.
 429           Implementations of this extension point must be derived from #GVfs.
 430           GIO uses the implementation with the highest priority that is active,
 431           see g_vfs_is_active().
 432        </para>
 433        <para>
 434           GIO implements this extension point for local files, gvfs contains
 435           an implementation that supports all the backends in gvfs.
 436        </para>
 437    </formalpara>
 438
 439    <formalpara>
 440       <title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 441
 442       <para>
 443          Allows to add more volume monitors.
 444          Implementations of this extension point must be derived from
 445          #GVolumeMonitor. GIO uses all registered extensions.
 446       </para>
 447       <para>
 448         gvfs contains an implementation that works together with the #GVfs
 449         implementation in gvfs.
 450       </para>
 451    </formalpara>
 452
 453    <formalpara>
 454       <title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 455
 456       <para>
 457          Allows to override the 'native' volume monitor.
 458          Implementations of this extension point must be derived from
 459          #GNativeVolumeMonitor. GIO uses the implementation with
 460          the highest priority that is supported, as determined by the
 461          is_supported() vfunc in #GVolumeMonitorClass.
 462       </para>
 463       <para>
 464          GIO implements this extension point for local mounts,
 465          gvfs contains a hal-based implementation.
 466       </para>
 467    </formalpara>
 468
 469    <formalpara>
 470       <title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
 471
 472       <para>
 473         Allows to override the file monitor implementation for
 474         local files. Implementations of this extension point must
 475         be derived from #GLocalFileMonitor. GIO uses the implementation
 476         with the highest priority that is supported, as determined by the
 477         is_supported() vfunc in #GLocalFileMonitorClass.
 478       </para>
 479       <para>
 480         GIO uses this extension point internally, to switch between
 481         its fam-based and inotify-based file monitoring implementations.
 482       </para>
 483    </formalpara>
 484
 485    <formalpara>
 486       <title>G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME</title>
 487
 488       <para>
 489         Allows to override the directory monitor implementation for
 490         local files. Implementations of this extension point must be
 491         derived from #GLocalDirectoryMonitor. GIO uses the implementation
 492         with the highest priority that is supported, as determined by the
 493         is_supported() vfunc in #GLocalDirectoryMonitorClass.
 494       </para>
 495       <para>
 496         GIO uses this extension point internally, to switch between
 497         its fam-based and inotify-based directory monitoring implementations.
 498       </para>
 499    </formalpara>
 500
 501    <formalpara>
 502       <title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
 503
 504       <para>
 505         Unix-only. Allows to provide a way to associate default handlers
 506         with URI schemes. Implementations of this extension point must
 507         implement the #GDesktopAppInfoLookup interface. GIO uses the
 508         implementation with the highest priority.
 509       </para>
 510       <para>
 511         gvfs contains a GConf-based implementation that uses the
 512         same GConf keys as gnome-vfs.
 513       </para>
 514    </formalpara>
 515
 516    <formalpara>
 517       <title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
 518
 519       <para>
 520         Allows to provide an alternative storage for #GSettings.
 521         Implementations of this extension point must derive from the
 522         #GSettingsBackend type. GIO contains a keyfile-based
 523         implementation of this extension point, another one is provided
 524         by dconf.
 525       </para>
 526    </formalpara>
 527   </chapter>
 528 </part>