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
 186     <para>
 187       Since GIO is based on GObject, you need to call g_type_init()
 188       before you can use any GIO functions. If your application uses
 189       GTK+, this is already taken care of by gtk_init().
 190     </para>
 191   </chapter>
 192
 193   <chapter>
 194     <title>Running GIO applications</title>
 195
 196     <para>
 197       GIO inspects a few of environment variables in addition to the
 198       ones used by GLib.
 199     </para>
 200
 201     <formalpara>
 202       <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
 203
 204       <para>
 205         GIO uses these environment variables to locate MIME information.
 206         For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
 207         and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
 208       </para>
 209     </formalpara>
 210
 211     <formalpara>
 212       <title><envar>GVFS_DISABLE_FUSE</envar></title>
 213
 214       <para>
 215         This variable can be set to keep #Gvfs from starting the fuse backend,
 216         which may be unwanted or unnecessary in certain situations.
 217       </para>
 218     </formalpara>
 219
 220     <para>
 221       The following environment variables are only useful for debugging
 222       GIO itself or modules that it loads. They should not be set in a
 223       production environment.
 224     </para>
 225     <formalpara>
 226       <title><envar>GIO_USE_VFS</envar></title>
 227
 228       <para>
 229         This environment variable can be set to the name of a #GVfs
 230         implementation to override the default for debugging purposes.
 231         The #GVfs implementation for local files that is included in GIO
 232         has the name "local", the implementation in the gvfs module has
 233         the name "gvfs".
 234       </para>
 235     </formalpara>
 236
 237     <formalpara>
 238       <title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
 239
 240       <para>
 241         This variable can be set to the name of a #GVolumeMonitor
 242         implementation to override the default for debugging purposes.
 243         The #GVolumeMonitor implementation for local files that is included
 244         in GIO has the name "unix", the hal-based implementation in the
 245         gvfs module has the name "hal".
 246       </para>
 247     </formalpara>
 248
 249     <formalpara>
 250       <title><envar>GIO_USE_TLS</envar></title>
 251
 252       <para>
 253         This variable can be set to the name of a #GTlsBackend
 254         implementation to override the default for debugging purposes.
 255         GIO does not include a #GTlsBackend implementation, the gnutls-based
 256         implementation in the glib-networking module has the name "gnutls".
 257       </para>
 258     </formalpara>
 259
 260     <formalpara>
 261       <title><envar>GVFS_INOTIFY_DIAG</envar></title>
 262
 263       <para>
 264         When this environment variable is set and GIO has been built
 265         with inotify support, a dump of diagnostic inotify information
 266         will be written every 20 seconds to a file named
 267         <filename>/tmp/gvfsdid.<replaceable>pid</replaceable></filename>.
 268       </para>
 269     </formalpara>
 270
 271     <formalpara>
 272       <title><envar>GIO_EXTRA_MODULES</envar></title>
 273
 274       <para>
 275         When this environment variable is set to a path, or a set of
 276         paths separated by a colon, GIO will attempt to load
 277         modules from within the path.
 278       </para>
 279     </formalpara>
 280
 281     <formalpara>
 282       <title><envar>GSETTINGS_BACKEND</envar></title>
 283
 284       <para>
 285         This variable can be set to the name of a #GSettingsBackend
 286         implementation to override the default for debugging purposes.
 287         The memory-based implementation that is included in GIO has
 288         the name "memory", the one in dconf has the name "dconf-settings".
 289       </para>
 290     </formalpara>
 291
 292     <formalpara>
 293       <title><envar>GSETTINGS_SCHEMA_DIR</envar></title>
 294
 295       <para>
 296         This variable can be set to the name of a directory that is
 297         considered in addition to the <filename>glib-2.0/schemas</filename>
 298         subdirectories of the XDG system data dirs when looking
 299         for compiled schemas for #GSettings.
 300       </para>
 301     </formalpara>
 302
 303    <formalpara>
 304       <title><envar>DBUS_SYSTEM_BUS_ADDRESS</envar></title>
 305
 306       <para>
 307         This variable is consulted to find the address of the D-Bus system
 308         bus. For the format of D-Bus addresses, see the D-Bus
 309         <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">specification</ulink>.
 310       </para>
 311       <para>
 312         Setting this variable overrides platform-specific ways of determining
 313         the system bus address.
 314       </para>
 315    </formalpara>
 316
 317    <formalpara>
 318       <title><envar>DBUS_SESSION_BUS_ADDRESS</envar></title>
 319
 320       <para>
 321         This variable is consulted to find the address of the D-Bus session bus.
 322       </para>
 323       <para>
 324         Setting this variable overrides platform-specific ways of determining
 325         the session bus address.
 326       </para>
 327    </formalpara>
 328
 329    <formalpara>
 330       <title><envar>DBUS_STARTER_BUS_TYPE</envar></title>
 331
 332       <para>
 333         This variable is consulted to find out the 'starter' bus for an
 334         application that has been started via D-Bus activation. The possible
 335         values are 'system' or 'session'.
 336       </para>
 337    </formalpara>
 338
 339    <formalpara>
 340       <title><envar>G_DBUS_DEBUG</envar></title>
 341
 342       <para>
 343          This variable can be set to a list of debug options, which
 344          cause GLib to print out different types of debugging
 345          information when using the D-Bus routines.
 346          <variablelist>
 347            <varlistentry>
 348              <term>transport</term>
 349              <listitem><para>Show IO activity (e.g. reads and writes)</para></listitem>
 350            </varlistentry>
 351            <varlistentry>
 352              <term>message</term>
 353              <listitem><para>Show all sent and received D-Bus messages</para></listitem>
 354            </varlistentry>
 355            <varlistentry>
 356              <term>payload</term>
 357              <listitem><para>Show payload for all sent and received D-Bus messages (implies message)</para></listitem>
 358            </varlistentry>
 359            <varlistentry>
 360              <term>call</term>
 361              <listitem><para>Trace g_dbus_connection_call() and g_dbus_connection_call_sync() API usage</para></listitem>
 362            </varlistentry>
 363            <varlistentry>
 364              <term>signal</term>
 365              <listitem><para>Show when a D-Bus signal is received</para></listitem>
 366            </varlistentry>
 367            <varlistentry>
 368              <term>incoming</term>
 369              <listitem><para>Show when an incoming D-Bus method call is received</para></listitem>
 370            </varlistentry>
 371            <varlistentry>
 372              <term>return</term>
 373              <listitem><para>Show when a reply is returned via the #GDBusMethodInvocation API</para></listitem>
 374            </varlistentry>
 375            <varlistentry>
 376              <term>emission</term>
 377              <listitem><para>Trace g_dbus_connection_emit_signal() API usage</para></listitem>
 378            </varlistentry>
 379            <varlistentry>
 380              <term>authentication</term>
 381              <listitem><para>Show information about connection authentication</para></listitem>
 382            </varlistentry>
 383            <varlistentry>
 384              <term>address</term>
 385              <listitem><para>Show information about D-Bus address lookups and autolaunching</para></listitem>
 386            </varlistentry>
 387          </variablelist>
 388          The special value <literal>all</literal> can be used to turn
 389          on all debug options. The special value
 390          <literal>help</literal> can be used to print a list of
 391          supported options to standard output.
 392       </para>
 393    </formalpara>
 394
 395    <formalpara>
 396       <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR</envar></title>
 397
 398       <para>
 399         Can be used to override the directory used to store the
 400         keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
 401         authentication mechanism. Normally the directory used is
 402         <filename>.dbus-keyrings</filename> in the user's home
 403         directory.
 404       </para>
 405    </formalpara>
 406
 407    <formalpara>
 408       <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION</envar></title>
 409
 410       <para>
 411         If set, the permissions of the directory used to store the
 412         keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
 413         authentication mechanism won't be checked. Normally the
 414         directory must be readable only by the user.
 415       </para>
 416    </formalpara>
 417   </chapter>
 418
 419   <chapter id="extending-gio">
 420     <title>Extending GIO</title>
 421
 422     <para>
 423       A lot of the functionality that is accessible through GIO
 424       is implemented in loadable modules, and modules provide a convenient
 425       way to extend GIO. In addition to the #GIOModule API which supports
 426       writing such modules, GIO has a mechanism to define extension points,
 427       and register implementations thereof, see #GIOExtensionPoint.
 428     </para>
 429     <para>
 430       The following extension points are currently defined by GIO:
 431     </para>
 432
 433     <formalpara>
 434        <title>G_VFS_EXTENSION_POINT_NAME</title>
 435
 436        <para>
 437           Allows to override the functionality of the #GVfs class.
 438           Implementations of this extension point must be derived from #GVfs.
 439           GIO uses the implementation with the highest priority that is active,
 440           see g_vfs_is_active().
 441        </para>
 442        <para>
 443           GIO implements this extension point for local files, gvfs contains
 444           an implementation that supports all the backends in gvfs.
 445        </para>
 446    </formalpara>
 447
 448    <formalpara>
 449       <title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 450
 451       <para>
 452          Allows to add more volume monitors.
 453          Implementations of this extension point must be derived from
 454          #GVolumeMonitor. GIO uses all registered extensions.
 455       </para>
 456       <para>
 457         gvfs contains an implementation that works together with the #GVfs
 458         implementation in gvfs.
 459       </para>
 460    </formalpara>
 461
 462    <formalpara>
 463       <title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 464
 465       <para>
 466          Allows to override the 'native' volume monitor.
 467          Implementations of this extension point must be derived from
 468          #GNativeVolumeMonitor. GIO uses the implementation with
 469          the highest priority that is supported, as determined by the
 470          is_supported() vfunc in #GVolumeMonitorClass.
 471       </para>
 472       <para>
 473          GIO implements this extension point for local mounts,
 474          gvfs contains a hal-based implementation.
 475       </para>
 476    </formalpara>
 477
 478    <formalpara>
 479       <title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
 480
 481       <para>
 482         Allows to override the file monitor implementation for
 483         local files. Implementations of this extension point must
 484         be derived from #GLocalFileMonitor. GIO uses the implementation
 485         with the highest priority that is supported, as determined by the
 486         is_supported() vfunc in #GLocalFileMonitorClass.
 487       </para>
 488       <para>
 489         GIO uses this extension point internally, to switch between
 490         its fam-based and inotify-based file monitoring implementations.
 491       </para>
 492    </formalpara>
 493
 494    <formalpara>
 495       <title>G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME</title>
 496
 497       <para>
 498         Allows to override the directory monitor implementation for
 499         local files. Implementations of this extension point must be
 500         derived from #GLocalDirectoryMonitor. GIO uses the implementation
 501         with the highest priority that is supported, as determined by the
 502         is_supported() vfunc in #GLocalDirectoryMonitorClass.
 503       </para>
 504       <para>
 505         GIO uses this extension point internally, to switch between
 506         its fam-based and inotify-based directory monitoring implementations.
 507       </para>
 508    </formalpara>
 509
 510    <formalpara>
 511       <title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
 512
 513       <para>
 514         Unix-only. Allows to provide a way to associate default handlers
 515         with URI schemes. Implementations of this extension point must
 516         implement the #GDesktopAppInfoLookup interface. GIO uses the
 517         implementation with the highest priority.
 518       </para>
 519       <para>
 520         This extension point has been discontinued in GLib 2.28. It is
 521         still available to keep API and ABI stability, but GIO is no
 522         longer using it for default handlers. Instead, the mime handler
 523         mechanism is used, together with x-scheme-handler pseudo-mimetypes.
 524       </para>
 525    </formalpara>
 526
 527    <formalpara>
 528       <title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
 529
 530       <para>
 531         Allows to provide an alternative storage for #GSettings.
 532         Implementations of this extension point must derive from the
 533         #GSettingsBackend type. GIO contains a keyfile-based
 534         implementation of this extension point, another one is provided
 535         by dconf.
 536       </para>
 537    </formalpara>
 538
 539    <formalpara>
 540      <title>G_PROXY_EXTENSION_POINT_NAME</title>
 541
 542      <para>
 543        Allows to provide implementations for network proxying.
 544        Implementations of this extension point must provide the
 545        #GProxy interface, and must be named after the network
 546        protocol they are proxying.
 547      </para>
 548      <para>
 549        glib-networking contains an implementation of this extension
 550        point based on libproxy.
 551      </para>
 552    </formalpara>
 553
 554    <formalpara>
 555      <title>G_TLS_BACKEND_EXTENSION_POINT_NAME</title>
 556
 557      <para>
 558        Allows to provide implementations for TLS support.
 559        Implementations of this extension point must implement
 560        the #GTlsBackend interface.
 561      </para>
 562      <para>
 563        glib-networking contains an implementation of this extension
 564        point.
 565      </para>
 566    </formalpara>
 567
 568   </chapter>
 569 </part>