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, as well as other generally
  10     useful APIs for desktop applications (such as networking and
  11     D-Bus support). The goal is to overcome the shortcomings of GnomeVFS
  12     and provide an API that is so good that developers prefer it over raw
  13     POSIX calls. Among other things that means using GObject. It also means
  14     not cloning the POSIX API, but providing higher-level, document-centric
  15     interfaces.
  16   </para>
  17
  18   <para>
  19     The abstract file system model of GIO consists of a number of
  20     interfaces and base classes for I/O and files:
  21     <variablelist>
  22        <varlistentry>
  23          <term>GFile</term>
  24          <listitem><para>reference to a file</para></listitem>
  25        </varlistentry>
  26        <varlistentry>
  27          <term>GFileInfo</term>
  28          <listitem><para>information about a file or filesystem</para></listitem>
  29        </varlistentry>
  30        <varlistentry>
  31          <term>GFileEnumerator</term>
  32          <listitem><para>list files in directories</para></listitem>
  33        </varlistentry>
  34        <varlistentry>
  35          <term>GDrive</term>
  36          <listitem><para>represents a drive</para></listitem>
  37        </varlistentry>
  38        <varlistentry>
  39          <term>GVolume</term>
  40          <listitem><para>represents a file system in an abstract way</para></listitem>
  41        </varlistentry>
  42        <varlistentry>
  43          <term>GMount</term>
  44          <listitem><para>represents a mounted file system</para></listitem>
  45        </varlistentry>
  46     </variablelist>
  47     Then there is a number of stream classes, similar to the input and
  48     output stream hierarchies that can be found in frameworks like Java:
  49     <variablelist>
  50        <varlistentry>
  51          <term>GInputStream</term>
  52          <listitem><para>read data</para></listitem>
  53        </varlistentry>
  54        <varlistentry>
  55          <term>GOutputStream</term>
  56          <listitem><para>write data</para></listitem>
  57        </varlistentry>
  58        <varlistentry>
  59          <term>GIOStream</term>
  60          <listitem><para>read and write data</para></listitem>
  61        </varlistentry>
  62        <varlistentry>
  63          <term>GSeekable</term>
  64          <listitem><para>interface optionally implemented by streams to support seeking</para></listitem>
  65        </varlistentry>
  66     </variablelist>
  67     There are interfaces related to applications and the types
  68     of files they handle:
  69     <variablelist>
  70        <varlistentry>
  71           <term>GAppInfo</term>
  72           <listitem><para>information about an installed application</para></listitem>
  73        </varlistentry>
  74        <varlistentry>
  75           <term>GIcon</term>
  76           <listitem><para>abstract type for file and application icons</para></listitem>
  77        </varlistentry>
  78     </variablelist>
  79     There is a framework for storing and retrieving application settings:
  80     <variablelist>
  81        <varlistentry>
  82           <term>GSettings</term>
  83           <listitem><para>stores and retrieves application settings</para></listitem>
  84        </varlistentry>
  85     </variablelist>
  86     There is support for network programming, including connectivity monitoring,
  87     name resolution, lowlevel socket APIs and highlevel client and server
  88     helper classes:
  89     <variablelist>
  90        <varlistentry>
  91           <term>GSocket</term>
  92           <listitem><para>lowlevel platform independent socket object</para></listitem>
  93        </varlistentry>
  94        <varlistentry>
  95           <term>GResolver</term>
  96           <listitem><para>asynchronous and cancellable DNS resolver</para></listitem>
  97        </varlistentry>
  98        <varlistentry>
  99           <term>GSocketClient</term>
 100           <listitem><para>high-level network client helper</para></listitem>
 101        </varlistentry>
 102        <varlistentry>
 103           <term>GSocketService</term>
 104           <listitem><para>high-level network server helper</para></listitem>
 105        </varlistentry>
 106        <varlistentry>
 107           <term>GSocketConnection</term>
 108           <listitem><para>network connection stream</para></listitem>
 109        </varlistentry>
 110        <varlistentry>
 111           <term>GNetworkMonitor</term>
 112           <listitem><para>network connectivity monitoring</para></listitem>
 113        </varlistentry>
 114     </variablelist>
 115     There is support for connecting to <link linkend="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</link>,
 116     sending and receiving messages, owning and watching bus names,
 117     and making objects available on the bus:
 118     <variablelist>
 119        <varlistentry>
 120           <term>GDBusConnection</term>
 121           <listitem><para>a D-Bus connection</para></listitem>
 122        </varlistentry>
 123
 124        <varlistentry>
 125           <term>GDBusMethodInvocation</term>
 126           <listitem><para>for handling remote calls</para></listitem>
 127        </varlistentry>
 128
 129        <varlistentry>
 130           <term>GDBusServer</term>
 131           <listitem><para>helper for accepting connections</para></listitem>
 132        </varlistentry>
 133
 134        <varlistentry>
 135           <term>GDBusProxy</term>
 136           <listitem><para>proxy to access D-Bus interfaces on a remote object</para></listitem>
 137        </varlistentry>
 138
 139     </variablelist>
 140     Beyond these, GIO provides facilities for file monitoring,
 141     asynchronous I/O and filename completion. In addition to the
 142     interfaces, GIO provides implementations for the local case.
 143     Implementations for various network file systems are provided
 144     by the GVFS package as loadable modules.
 145   </para>
 146
 147   <para>
 148     Other design choices which consciously break with the GnomeVFS
 149     design are to move backends out-of-process, which minimizes the
 150     dependency bloat and makes the whole system more robust. The backends
 151     are not included in GIO, but in the separate GVFS package. The GVFS
 152     package also contains the GVFS daemon, which spawn further mount
 153     daemons for each individual connection.
 154   </para>
 155
 156   <figure id="gvfs-overview">
 157     <title>GIO in the GTK+ library stack</title>
 158     <graphic fileref="gvfs-overview.png" format="PNG"></graphic>
 159   </figure>
 160
 161   <para>
 162     The GIO model of I/O is stateful: if an application establishes e.g.
 163     a SFTP connection to a server, it becomes available to all applications
 164     in the session; the user does not have to enter his password over
 165     and over again.
 166   </para>
 167   <para>
 168     One of the big advantages of putting the VFS in the GLib layer
 169     is that GTK+ can directly use it, e.g. in the filechooser.
 170   </para>
 171   </chapter>
 172
 173   <chapter>
 174     <title>Writing GIO applications</title>
 175
 176     <para>
 177       The information in the GLib <ulink url="http://developer.gnome.org/glib/stable/glib-programming.html">documentation</ulink> about writing GLib
 178       applications is generally applicable when writing GIO applications.
 179     </para>
 180
 181     <simplesect><title>Threads</title>
 182
 183     <para>
 184        GDBus has its own private worker thread, so applications using
 185        GDBus have at least 3 threads. GIO makes heavy use of the concept
 186        of a <link linkend="g-main-context-push-thread-default">thread-default
 187        main context</link> to execute callbacks of asynchronous
 188        methods in the same context in which the operation was started.
 189     </para>
 190
 191     </simplesect>
 192
 193     <simplesect id="async-programming"><title>Asynchronous Programming</title>
 194
 195     <para>
 196       Many GIO functions come in two versions: synchronous and asynchronous,
 197       denoted by an <code>_async</code> suffix. It is important to use these
 198       appropriately: synchronous calls should not be used from
 199       within a main loop which is shared with other code, such as one in the
 200       application’s main thread. Synchronous calls block until they complete,
 201       and I/O operations can take noticeable amounts of time (even on ‘fast’
 202       SSDs). Blocking a main loop iteration while waiting for I/O means that
 203       other sources in the main loop will not be dispatched, such as input and
 204       redraw handlers for the application’s UI. This can cause the application
 205       to ‘freeze’ until I/O completes.
 206     </para>
 207
 208     <para>
 209       A few self-contained groups of functions, such as code generated by
 210       <link linkend="gdbus-codegen"><application>gdbus-codegen</application></link>,
 211       use a different convention: functions are asynchronous default, and it is
 212       the <emphasis>synchronous</emphasis> version which has a
 213       <code>_sync</code>
 214       suffix. Aside from naming differences, they should be treated the same
 215       way as functions following the normal convention above.
 216     </para>
 217
 218     <para>
 219       The asynchronous (<code>_async</code>) versions of functions return
 220       control to the caller immediately, after scheduling the I/O in the kernel
 221       and adding a callback for it to the main loop. This callback will be
 222       invoked when the operation has completed. From the callback, the paired
 223       <code>_finish</code> function should be called to retrieve the return
 224       value of the I/O operation, and any errors which occurred. For more
 225       information on using and implementing asynchronous functions, see
 226       <link linkend="GAsyncResult.description"><type>GAsyncResult</type></link>
 227       and <link linkend="GTask.description"><type>GTask</type></link>.
 228     </para>
 229
 230     <para>
 231       By starting multiple asynchronous operations in succession, they will be
 232       executed in parallel (up to an arbitrary limit imposed by GIO’s internal
 233       worker thread pool).
 234     </para>
 235
 236     <para>
 237       The synchronous versions of functions can be used early in application
 238       startup when there is no main loop to block, for example to load initial
 239       configuration files. They can also be used for I/O on files which are
 240       guaranteed to be small and on the local disk. Note that the user’s home
 241       directory is not guaranteed to be on the local disk.
 242     </para>
 243     </simplesect>
 244
 245     <simplesect><title>Security</title>
 246
 247 <para>
 248 When your program needs to carry out some privileged operation (say,
 249 create a new user account), there are various ways in which you can go
 250 about this:
 251 <itemizedlist>
 252 <listitem><para>
 253 Implement a daemon that offers the privileged operation. A convenient
 254 way to do this is as a D-Bus system-bus service. The daemon will probably
 255 need ways to check the identity and authorization of the caller before
 256 executing the operation. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html">polkit</ulink> is a framework that allows this.
 257 </para></listitem>
 258 <listitem><para>
 259 Use a small helper that is executed with elevated privileges via
 260 pkexec. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html">pkexec</ulink> is a small program launcher that is part of polkit.
 261 </para></listitem>
 262 <listitem><para>
 263 Use a small helper that is executed with elevated privileges by
 264 being suid root.
 265 </para></listitem>
 266 </itemizedlist>
 267 None of these approaches is the clear winner, they all have their
 268 advantages and disadvantages.
 269 </para>
 270
 271 <para>
 272 When writing code that runs with elevated privileges, it is important
 273 to follow some basic rules of secure programming. David Wheeler has an
 274 excellent book on this topic,
 275 <ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.
 276 </para>
 277
 278 <para>
 279 When using GIO in code that runs with elevated privileges, you have to
 280 be careful. GIO has extension points whose implementations get loaded
 281 from modules (executable code in shared objects), which could allow
 282 an attacker to sneak his own code into your application by tricking it
 283 into loading the code as a module. However, GIO will never load modules
 284 from your home directory except when explictly asked to do so via an
 285 environment variable.
 286 </para>
 287
 288 <para>
 289 In most cases, your helper program should be so small that you don't
 290 need GIO, whose APIs are largely designed to support full-blown desktop
 291 applications. If you can't resist the convenience of these APIs, here
 292 are some steps you should take:
 293 <itemizedlist>
 294 <listitem><para>
 295 Clear the environment, e.g. using the <function>clearenv()</function>
 296 function.
 297 David Wheeler has a good <ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/environment-variables.html">explanation</ulink> for why it is
 298 important to sanitize the environment.
 299 See <xref linkend="running-gio-apps"/>
 300 for a list of all environment variables affecting GIO. In particular,
 301 <envar>PATH</envar> (used to locate binaries), <envar>GIO_EXTRA_MODULES</envar> (used to locate loadable modules) and <envar>DBUS_{SYSTEM,SESSION}_BUS_ADDRESS</envar> (used to locate the D-Bus system and session bus) are important.
 302 </para></listitem>
 303 <listitem><para>
 304 Don't use GVfs, by setting <envar>GIO_USE_VFS=local</envar> in the environment.
 305 The reason to avoid GVfs in security-sensitive programs is that it uses
 306 many libraries which have not necessarily been audited for security problems.
 307 Gvfs is also heavily distributed and relies on a session bus to be present.
 308 </para></listitem>
 309 </itemizedlist>
 310 </para>
 311
 312     </simplesect>
 313
 314   </chapter>
 315
 316   <chapter>
 317     <title>Compiling GIO applications</title>
 318
 319     <para>
 320       GIO comes with a <filename>gio-2.0.pc</filename> file that you
 321       should use together with <literal>pkg-config</literal> to obtain
 322       the necessary information about header files and libraries. See
 323       the <literal>pkg-config</literal> man page or the GLib documentation
 324       for more information on how to use <literal>pkg-config</literal>
 325       to compile your application.
 326     </para>
 327
 328     <para>
 329       If you are using GIO on UNIX-like systems, you may want to use
 330       UNIX-specific GIO interfaces such as #GUnixInputStream,
 331       #GUnixOutputStream, #GUnixMount or #GDesktopAppInfo.
 332       To do so, use the <filename>gio-unix-2.0.pc</filename> file
 333       instead of <filename>gio-2.0.pc</filename>
 334     </para>
 335   </chapter>
 336
 337   <chapter id="running-gio-apps">
 338     <title>Running GIO applications</title>
 339
 340     <para>
 341       GIO inspects a few environment variables in addition to the
 342       ones used by GLib.
 343     </para>
 344
 345     <formalpara>
 346       <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
 347
 348       <para>
 349         GIO uses these environment variables to locate MIME information.
 350         For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
 351         and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
 352       </para>
 353     </formalpara>
 354
 355     <formalpara>
 356       <title><envar>GVFS_DISABLE_FUSE</envar></title>
 357
 358       <para>
 359         This variable can be set to keep #Gvfs from starting the fuse backend,
 360         which may be unwanted or unnecessary in certain situations.
 361       </para>
 362     </formalpara>
 363
 364     <formalpara>
 365       <title><envar>GIO_USE_VFS</envar></title>
 366
 367       <para>
 368         This environment variable can be set to the name of a #GVfs
 369         implementation to override the default for debugging purposes.
 370         The #GVfs implementation for local files that is included in GIO
 371         has the name "local", the implementation in the gvfs module has
 372         the name "gvfs".  Most commonly, system software will set this to "local"
 373         to avoid having `GFile` APIs perform unnecessary DBus calls.
 374       </para>
 375     </formalpara>
 376
 377     <para>
 378       The following environment variables are only useful for debugging
 379       GIO itself or modules that it loads. They should not be set in a
 380       production environment.
 381     </para>
 382
 383     <formalpara>
 384       <title><envar>GIO_USE_FILE_MONITOR</envar></title>
 385
 386       <para>
 387         This variable can be set to the name of a #GFileMonitor
 388         implementation to override the default for debugging purposes.
 389         The #GFileMonitor implementation for local files that is included
 390         in GIO on Linux has the name "inotify", others that are built
 391         are built as modules (depending on the platform) are called
 392         "fam" and "fen".
 393       </para>
 394     </formalpara>
 395
 396     <formalpara>
 397       <title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
 398
 399       <para>
 400         This variable can be set to the name of a #GVolumeMonitor
 401         implementation to override the default for debugging purposes.
 402         The #GVolumeMonitor implementation for local files that is included
 403         in GIO has the name "unix", the udisks2-based implementation in the
 404         gvfs module has the name "udisks2".
 405       </para>
 406     </formalpara>
 407
 408     <formalpara>
 409       <title><envar>GIO_USE_TLS</envar></title>
 410
 411       <para>
 412         This variable can be set to the name of a #GTlsBackend
 413         implementation to override the default for debugging purposes.
 414         GIO does not include a #GTlsBackend implementation, the gnutls-based
 415         implementation in the glib-networking module has the name "gnutls".
 416       </para>
 417     </formalpara>
 418
 419     <formalpara>
 420       <title><envar>GIO_MODULE_DIR</envar></title>
 421
 422       <para>
 423         When this environment variable is set to a path, GIO will load
 424         modules from this alternate directory instead of the directory
 425         built into GIO. This is useful when running tests, for example.
 426       </para>
 427     </formalpara>
 428
 429     <formalpara>
 430       <title><envar>GIO_EXTRA_MODULES</envar></title>
 431
 432       <para>
 433         When this environment variable is set to a path, or a set of
 434         paths separated by a colon, GIO will attempt to load
 435         additional modules from within the path.
 436       </para>
 437     </formalpara>
 438
 439     <formalpara>
 440       <title><envar>GSETTINGS_BACKEND</envar></title>
 441
 442       <para>
 443         This variable can be set to the name of a #GSettingsBackend
 444         implementation to override the default for debugging purposes.
 445         The memory-based implementation that is included in GIO has
 446         the name "memory", the one in dconf has the name "dconf-settings".
 447       </para>
 448     </formalpara>
 449
 450     <formalpara>
 451       <title><envar>GSETTINGS_SCHEMA_DIR</envar></title>
 452
 453       <para>
 454         This variable can be set to the name of a directory that is
 455         considered in addition to the <filename>glib-2.0/schemas</filename>
 456         subdirectories of the XDG system data dirs when looking
 457         for compiled schemas for #GSettings.
 458       </para>
 459     </formalpara>
 460
 461    <formalpara>
 462       <title><envar>DBUS_SYSTEM_BUS_ADDRESS</envar></title>
 463
 464       <para>
 465         This variable is consulted to find the address of the D-Bus system
 466         bus. For the format of D-Bus addresses, see the D-Bus
 467         <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">specification</ulink>.
 468       </para>
 469       <para>
 470         Setting this variable overrides platform-specific ways of determining
 471         the system bus address.
 472       </para>
 473    </formalpara>
 474
 475    <formalpara>
 476       <title><envar>DBUS_SESSION_BUS_ADDRESS</envar></title>
 477
 478       <para>
 479         This variable is consulted to find the address of the D-Bus session bus.
 480       </para>
 481       <para>
 482         Setting this variable overrides platform-specific ways of determining
 483         the session bus address.
 484       </para>
 485    </formalpara>
 486
 487    <formalpara>
 488       <title><envar>DBUS_STARTER_BUS_TYPE</envar></title>
 489
 490       <para>
 491         This variable is consulted to find out the 'starter' bus for an
 492         application that has been started via D-Bus activation. The possible
 493         values are 'system' or 'session'.
 494       </para>
 495    </formalpara>
 496
 497    <formalpara>
 498       <title><envar>G_DBUS_DEBUG</envar></title>
 499
 500       <para>
 501          This variable can be set to a list of debug options, which
 502          cause GLib to print out different types of debugging
 503          information when using the D-Bus routines.
 504          <variablelist>
 505            <varlistentry>
 506              <term>transport</term>
 507              <listitem><para>Show IO activity (e.g. reads and writes)</para></listitem>
 508            </varlistentry>
 509            <varlistentry>
 510              <term>message</term>
 511              <listitem><para>Show all sent and received D-Bus messages</para></listitem>
 512            </varlistentry>
 513            <varlistentry>
 514              <term>payload</term>
 515              <listitem><para>Show payload for all sent and received D-Bus messages (implies message)</para></listitem>
 516            </varlistentry>
 517            <varlistentry>
 518              <term>call</term>
 519              <listitem><para>Trace g_dbus_connection_call() and g_dbus_connection_call_sync() API usage</para></listitem>
 520            </varlistentry>
 521            <varlistentry>
 522              <term>signal</term>
 523              <listitem><para>Show when a D-Bus signal is received</para></listitem>
 524            </varlistentry>
 525            <varlistentry>
 526              <term>incoming</term>
 527              <listitem><para>Show when an incoming D-Bus method call is received</para></listitem>
 528            </varlistentry>
 529            <varlistentry>
 530              <term>return</term>
 531              <listitem><para>Show when a reply is returned via the #GDBusMethodInvocation API</para></listitem>
 532            </varlistentry>
 533            <varlistentry>
 534              <term>emission</term>
 535              <listitem><para>Trace g_dbus_connection_emit_signal() API usage</para></listitem>
 536            </varlistentry>
 537            <varlistentry>
 538              <term>authentication</term>
 539              <listitem><para>Show information about connection authentication</para></listitem>
 540            </varlistentry>
 541            <varlistentry>
 542              <term>address</term>
 543              <listitem><para>Show information about D-Bus address lookups and autolaunching</para></listitem>
 544            </varlistentry>
 545          </variablelist>
 546          The special value <literal>all</literal> can be used to turn
 547          on all debug options. The special value
 548          <literal>help</literal> can be used to print a list of
 549          supported options to standard output.
 550       </para>
 551    </formalpara>
 552
 553    <formalpara>
 554       <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR</envar></title>
 555
 556       <para>
 557         Can be used to override the directory used to store the
 558         keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
 559         authentication mechanism. Normally the directory used is
 560         <filename>.dbus-keyrings</filename> in the user's home
 561         directory.
 562       </para>
 563    </formalpara>
 564
 565    <formalpara>
 566       <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION</envar></title>
 567
 568       <para>
 569         If set, the permissions of the directory used to store the
 570         keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
 571         authentication mechanism won't be checked. Normally the
 572         directory must be readable only by the user.
 573       </para>
 574    </formalpara>
 575   </chapter>
 576
 577   <chapter id="extending-gio">
 578     <title>Extending GIO</title>
 579
 580     <para>
 581       A lot of the functionality that is accessible through GIO
 582       is implemented in loadable modules, and modules provide a convenient
 583       way to extend GIO. In addition to the #GIOModule API which supports
 584       writing such modules, GIO has a mechanism to define extension points,
 585       and register implementations thereof, see #GIOExtensionPoint.
 586     </para>
 587     <para>
 588       The following extension points are currently defined by GIO:
 589     </para>
 590
 591     <formalpara>
 592        <title>G_VFS_EXTENSION_POINT_NAME</title>
 593
 594        <para>
 595           Allows to override the functionality of the #GVfs class.
 596           Implementations of this extension point must be derived from #GVfs.
 597           GIO uses the implementation with the highest priority that is active,
 598           see g_vfs_is_active().
 599        </para>
 600        <para>
 601           GIO implements this extension point for local files, gvfs contains
 602           an implementation that supports all the backends in gvfs.
 603        </para>
 604    </formalpara>
 605
 606    <formalpara>
 607       <title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 608
 609       <para>
 610          Allows to add more volume monitors.
 611          Implementations of this extension point must be derived from
 612          #GVolumeMonitor. GIO uses all registered extensions.
 613       </para>
 614       <para>
 615         gvfs contains an implementation that works together with the #GVfs
 616         implementation in gvfs.
 617       </para>
 618    </formalpara>
 619
 620    <formalpara>
 621       <title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
 622
 623       <para>
 624          Allows to override the 'native' volume monitor.
 625          Implementations of this extension point must be derived from
 626          #GNativeVolumeMonitor. GIO uses the implementation with
 627          the highest priority that is supported, as determined by the
 628          is_supported() vfunc in #GVolumeMonitorClass.
 629       </para>
 630       <para>
 631          GIO implements this extension point for local mounts,
 632          gvfs contains a udisks2-based implementation.
 633       </para>
 634    </formalpara>
 635
 636    <formalpara>
 637       <title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
 638
 639       <para>
 640         Allows to override the file monitor implementation for
 641         local files. Implementations of this extension point must
 642         be derived from #GLocalFileMonitor. GIO uses the implementation
 643         with the highest priority that is supported, as determined by the
 644         is_supported() vfunc in #GLocalFileMonitorClass.
 645       </para>
 646       <para>
 647         GIO uses this extension point internally, to switch between
 648         its fam-based and inotify-based file monitoring implementations.
 649       </para>
 650    </formalpara>
 651
 652    <formalpara>
 653       <title>G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME</title>
 654
 655       <para>
 656         Allows to override the directory monitor implementation for
 657         local files. Implementations of this extension point must be
 658         derived from #GLocalDirectoryMonitor. GIO uses the implementation
 659         with the highest priority that is supported, as determined by the
 660         is_supported() vfunc in #GLocalDirectoryMonitorClass.
 661       </para>
 662       <para>
 663         GIO uses this extension point internally, to switch between
 664         its fam-based and inotify-based directory monitoring implementations.
 665       </para>
 666    </formalpara>
 667
 668    <formalpara>
 669       <title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
 670
 671       <para>
 672         Unix-only. Allows to provide a way to associate default handlers
 673         with URI schemes. Implementations of this extension point must
 674         implement the #GDesktopAppInfoLookup interface. GIO uses the
 675         implementation with the highest priority.
 676       </para>
 677       <para>
 678         This extension point has been discontinued in GLib 2.28. It is
 679         still available to keep API and ABI stability, but GIO is no
 680         longer using it for default handlers. Instead, the mime handler
 681         mechanism is used, together with x-scheme-handler pseudo-mimetypes.
 682       </para>
 683    </formalpara>
 684
 685    <formalpara>
 686       <title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
 687
 688       <para>
 689         Allows to provide an alternative storage for #GSettings.
 690         Implementations of this extension point must derive from the
 691         #GSettingsBackend type. GIO contains a keyfile-based
 692         implementation of this extension point, another one is provided
 693         by dconf.
 694       </para>
 695    </formalpara>
 696
 697    <formalpara>
 698      <title>G_PROXY_EXTENSION_POINT_NAME</title>
 699
 700      <para>
 701        Allows to provide implementations for network proxying.
 702        Implementations of this extension point must provide the
 703        #GProxy interface, and must be named after the network
 704        protocol they are proxying.
 705      </para>
 706      <para>
 707        glib-networking contains an implementation of this extension
 708        point based on libproxy.
 709      </para>
 710    </formalpara>
 711    <formalpara>
 712      <title>G_TLS_BACKEND_EXTENSION_POINT_NAME</title>
 713
 714      <para>
 715        Allows to provide implementations for TLS support.
 716        Implementations of this extension point must implement
 717        the #GTlsBackend interface.
 718      </para>
 719      <para>
 720        glib-networking contains an implementation of this extension
 721        point.
 722      </para>
 723    </formalpara>
 724
 725    <formalpara>
 726      <title>G_NETWORK_MONITOR_EXTENSION_POINT_NAME</title>
 727
 728      <para>
 729        Allows to provide implementations for network connectivity
 730        monitoring.
 731        Implementations of this extension point must implement
 732        the #GNetworkMonitorInterface interface.
 733      </para>
 734      <para>
 735        GIO contains an implementation of this extension point
 736        that is using the netlink interface of the Linux kernel.
 737      </para>
 738    </formalpara>
 739   </chapter>
 740 </part>
 741