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>emission</term>
 364              <listitem><para>Trace g_dbus_connection_emit_signal() API usage</para></listitem>
 365            </varlistentry>
 366            <varlistentry>
 367              <term>authentication</term>
 368              <listitem><para>Show information about connection authentication</para></listitem>
 369            </varlistentry>
 370            <varlistentry>
 371              <term>address</term>
 372              <listitem><para>Show information about D-Bus address lookups and autolaunching</para></listitem>
 373            </varlistentry>
 374          </variablelist>
 375          The special value <literal>all</literal> can be used to turn on
 376          all debug options.
 377       </para>
 378    </formalpara>
 379
 380    <formalpara>
 381       <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR</envar></title>
 382
 383       <para>
 384         Can be used to override the directory used to store the
 385         keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
 386         authentication mechanism. Normally the directory used is
 387         <filename>.dbus-keyrings</filename> in the user's home
 388         directory.
 389       </para>
 390    </formalpara>
 391
 392    <formalpara>
 393       <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION</envar></title>
 394
 395       <para>
 396         If set, the permissions of the directory used to store the
 397         keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
 398         authentication mechanism won't be checked. Normally the
 399         directory must be readable only by the user.
 400       </para>
 401    </formalpara>
 402   </chapter>
 403
 404   <chapter id="extending-gio">
 405     <title>Extending GIO</title>
 406
 407     <para>
 408       A lot of the functionality that is accessible through GIO
 409       is implemented in loadable modules, and modules provide a convenient
 410       way to extend GIO. In addition to the #GIOModule API which supports
 411       writing such modules, GIO has a mechanism to define extension points,
 412       and register implementations thereof, see #GIOExtensionPoint.
 413     </para>
 414     <para>
 415       The following extension points are currently defined by GIO:
 416     </para>
 417
 418     <formalpara>
 419        <title>G_VFS_EXTENSION_POINT_NAME</title>
 420
 421        <para>
 422           Allows to override the functionality of the #GVfs class.
 423           Implementations of this extension point must be derived from #GVfs.
 424           GIO uses the implementation with the highest priority that is active,
 425           see g_vfs_is_active().
 426        </para>
 427        <para>
 428           GIO implements this extension point for local files, gvfs contains
 429           an implementation that supports all the backends in gvfs.
 430        </para>
 431    </formalpara>
 432
 433    <formalpara>
 434       <title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 435
 436       <para>
 437          Allows to add more volume monitors.
 438          Implementations of this extension point must be derived from
 439          #GVolumeMonitor. GIO uses all registered extensions.
 440       </para>
 441       <para>
 442         gvfs contains an implementation that works together with the #GVfs
 443         implementation in gvfs.
 444       </para>
 445    </formalpara>
 446
 447    <formalpara>
 448       <title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 449
 450       <para>
 451          Allows to override the 'native' volume monitor.
 452          Implementations of this extension point must be derived from
 453          #GNativeVolumeMonitor. GIO uses the implementation with
 454          the highest priority that is supported, as determined by the
 455          is_supported() vfunc in #GVolumeMonitorClass.
 456       </para>
 457       <para>
 458          GIO implements this extension point for local mounts,
 459          gvfs contains a hal-based implementation.
 460       </para>
 461    </formalpara>
 462
 463    <formalpara>
 464       <title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
 465
 466       <para>
 467         Allows to override the file monitor implementation for
 468         local files. Implementations of this extension point must
 469         be derived from #GLocalFileMonitor. GIO uses the implementation
 470         with the highest priority that is supported, as determined by the
 471         is_supported() vfunc in #GLocalFileMonitorClass.
 472       </para>
 473       <para>
 474         GIO uses this extension point internally, to switch between
 475         its fam-based and inotify-based file monitoring implementations.
 476       </para>
 477    </formalpara>
 478
 479    <formalpara>
 480       <title>G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME</title>
 481
 482       <para>
 483         Allows to override the directory monitor implementation for
 484         local files. Implementations of this extension point must be
 485         derived from #GLocalDirectoryMonitor. GIO uses the implementation
 486         with the highest priority that is supported, as determined by the
 487         is_supported() vfunc in #GLocalDirectoryMonitorClass.
 488       </para>
 489       <para>
 490         GIO uses this extension point internally, to switch between
 491         its fam-based and inotify-based directory monitoring implementations.
 492       </para>
 493    </formalpara>
 494
 495    <formalpara>
 496       <title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
 497
 498       <para>
 499         Unix-only. Allows to provide a way to associate default handlers
 500         with URI schemes. Implementations of this extension point must
 501         implement the #GDesktopAppInfoLookup interface. GIO uses the
 502         implementation with the highest priority.
 503       </para>
 504       <para>
 505         gvfs contains a GConf-based implementation that uses the
 506         same GConf keys as gnome-vfs.
 507       </para>
 508    </formalpara>
 509
 510    <formalpara>
 511       <title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
 512
 513       <para>
 514         Allows to provide an alternative storage for #GSettings.
 515         Implementations of this extension point must derive from the
 516         #GSettingsBackend type. GIO contains a keyfile-based
 517         implementation of this extension point, another one is provided
 518         by dconf.
 519       </para>
 520    </formalpara>
 521   </chapter>
 522 </part>