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