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>GSeekable</term> 58 <listitem><para>interface optionally implemented by streams to support seeking</para></listitem> 59 </varlistentry> 60 </variablelist> 61 There are interfaces related to applications and the types 62 of files they handle: 63 <variablelist> 64 <varlistentry> 65 <term>GAppInfo</term> 66 <listitem><para>information about an installed application</para></listitem> 67 </varlistentry> 68 <varlistentry> 69 <term>GIcon</term> 70 <listitem><para>abstract type for file and application icons</para></listitem> 71 </varlistentry> 72 </variablelist> 73 Beyond these, GIO provides facilities for file monitoring, 74 asynchronous I/O and filename completion. In addition to the 75 interfaces, GIO provides implementations for the local case. 76 Implementations for various network file systems are provided 77 by the GVFS package as loadable modules. 78 </para> 79 80 <para> 81 Other design choices which consciously break with the GnomeVFS 82 design are to move backends out-of-process, which minimizes the 83 dependency bloat and makes the whole system more robust. The backends 84 are not included in GIO, but in the separate GVFS package. The GVFS 85 package also contains the GVFS daemon, which spawn further mount 86 daemons for each individual connection. 87 </para> 88 89 <figure id="gvfs-overview"> 90 <title>GIO in the GTK+ library stack</title> 91 <graphic fileref="gvfs-overview.png" format="PNG"></graphic> 92 </figure> 93 94 <para> 95 The GIO model of I/O is stateful: if an application establishes e.g. 96 a SFTP connection to a server, it becomes available to all applications 97 in the session; the user does not have to enter his password over 98 and over again. 99 </para> 100 <para> 101 One of the big advantages of putting the VFS in the GLib layer 102 is that GTK+ can directly use it, e.g. in the filechooser. 103 </para> 104 </chapter> 105 106 <chapter> 107 <title>Compiling GIO applications</title> 108 109 <para> 110 GIO comes with a <filename>gio-2.0.pc</filename> file that you 111 should use together with <literal>pkg-config</literal> to obtain 112 the necessary information about header files and libraries. See 113 the <literal>pkg-config</literal> man page or the GLib documentation 114 for more information on how to use <literal>pkg-config</literal> 115 to compile your application. 116 </para> 117 118 <para> 119 If you are using GIO on UNIX-like systems, you may want to use 120 UNIX-specific GIO interfaces such as #GUnixInputStream, 121 #GUnixOutputStream, #GUnixMount or #GDesktopAppInfo. 122 To do so, use the <filename>gio-unix-2.0.pc</filename> file 123 instead of <filename>gio-2.0.pc</filename> 124 </para> 125 </chapter> 126 127 <chapter> 128 <title>Running GIO applications</title> 129 130 <para> 131 GIO inspects a few of environment variables in addition to the 132 ones used by GLib. 133 </para> 134 135 <formalpara> 136 <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title> 137 138 <para> 139 GIO uses these environment variables to locate MIME information. 140 For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink> 141 and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>. 142 </para> 143 </formalpara> 144 145 <formalpara> 146 <title><envar>GVFS_DISABLE_FUSE</envar></title> 147 148 <para> 149 This variable can be set to keep #Gvfs from starting the fuse backend, 150 which may be unwanted or unnecessary in certain situations. 151 </para> 152 </formalpara> 153 154 <para> 155 The following environment variables are only useful for debugging 156 GIO itself or modules that it loads. They should not be set in a 157 production environment. 158 </para> 159 <formalpara> 160 <title><envar>GIO_USE_VFS</envar></title> 161 162 <para> 163 This environment variable can be set to the name of a #GVfs 164 implementation to override the default for debugging purposes. 165 The #GVfs implementation for local files that is included in GIO 166 has the name "local", the implementation in the gvfs module has 167 the name "gvfs". 168 </para> 169 </formalpara> 170 171 <formalpara> 172 <title><envar>GIO_USE_VOLUME_MONITOR</envar></title> 173 174 <para> 175 This variable can be set to the name of a #GVolumeMonitor 176 implementation to override the default for debugging purposes. 177 The #GVolumeMonitor implementation for local files that is included 178 in GIO has the name "unix", the hal-based implementation in the 179 gvfs module has the name "hal". 180 </para> 181 </formalpara> 182 183 <formalpara> 184 <title><envar>GIO_USE_URI_ASSOCIATION</envar></title> 185 186 <para> 187 This variable can be set to the name of a #GDesktopAppInfoLookup 188 implementation to override the default for debugging purposes. 189 GIO does not include a #GDesktopAppInfoLookup implementation, 190 the GConf-based implementation in the gvfs module has the name 191 "gconf". 192 </para> 193 </formalpara> 194 195 <formalpara> 196 <title><envar>GVFS_INOTIFY_DIAG</envar></title> 197 198 <para> 199 When this environment variable is set and GIO has been built 200 with inotify support, a dump of diagnostic inotify information 201 will be written every 20 seconds to a file named 202 <filename>/tmp/gvfsdid.<replaceable>pid</replaceable></filename>. 203 </para> 204 </formalpara> 205 206 <formalpara> 207 <title><envar>GIO_EXTRA_MODULES</envar></title> 208 209 <para> 210 When this environment variable is set to a path, or a set of 211 paths separated by a colon, GIO will attempt to load 212 modules from within the path. 213 </para> 214 </formalpara> 215 216 </chapter> 217 218 <chapter id="extending-gio"> 219 <title>Extending GIO</title> 220 221 <para> 222 A lot of the functionality that is accessible through GIO 223 is implemented in loadable modules, and modules provide a convenient 224 way to extend GIO. In addition to the #GIOModule API which supports 225 writing such modules, GIO has a mechanism to define extension points, 226 and register implementations thereof, see #GIOExtensionPoint. 227 </para> 228 <para> 229 The following extension points are currently defined by GIO: 230 </para> 231 232 <formalpara> 233 <title>G_VFS_EXTENSION_POINT_NAME</title> 234 235 <para> 236 Allows to override the functionality of the #GVfs class. 237 Implementations of this extension point must be derived from #GVfs. 238 GIO uses the implementation with the highest priority that is active, 239 see g_vfs_is_active(). 240 </para> 241 <para> 242 GIO implements this extension point for local files, gvfs contains 243 an implementation that supports all the backends in gvfs. 244 </para> 245 </formalpara> 246 247 <formalpara> 248 <title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title> 249 250 <para> 251 Allows to add more volume monitors. 252 Implementations of this extension point must be derived from 253 #GVolumeMonitor. GIO uses all registered extensions. 254 </para> 255 <para> 256 gvfs contains an implementation that works together with the #GVfs 257 implementation in gvfs. 258 </para> 259 </formalpara> 260 261 <formalpara> 262 <title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title> 263 264 <para> 265 Allows to override the 'native' volume monitor. 266 Implementations of this extension point must be derived from 267 #GNativeVolumeMonitor. GIO uses the implementation with 268 the highest priority that is supported, as determined by the 269 is_supported() vfunc in #GVolumeMonitorClass. 270 </para> 271 <para> 272 GIO implements this extension point for local mounts, 273 gvfs contains a hal-based implementation. 274 </para> 275 </formalpara> 276 277 <formalpara> 278 <title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title> 279 280 <para> 281 Allows to override the file monitor implementation for 282 local files. Implementations of this extension point must 283 be derived from #GLocalFileMonitor. GIO uses the implementation 284 with the highest priority that is supported, as determined by the 285 is_supported() vfunc in #GLocalFileMonitorClass. 286 </para> 287 <para> 288 GIO uses this extension point internally, to switch between 289 its fam-based and inotify-based file monitoring implementations. 290 </para> 291 </formalpara> 292 293 <formalpara> 294 <title>G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME</title> 295 296 <para> 297 Allows to override the directory monitor implementation for 298 local files. Implementations of this extension point must be 299 derived from #GLocalDirectoryMonitor. GIO uses the implementation 300 with the highest priority that is supported, as determined by the 301 is_supported() vfunc in #GLocalDirectoryMonitorClass. 302 </para> 303 <para> 304 GIO uses this extension point internally, to switch between 305 its fam-based and inotify-based directory monitoring implementations. 306 </para> 307 </formalpara> 308 309 <formalpara> 310 <title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title> 311 312 <para> 313 Unix-only. Allows to provide a way to associate default handlers 314 with URI schemes. Implementations of this extension point must 315 implement the #GDesktopAppInfoLookup interface. GIO uses the 316 implementation with the highest priority. 317 </para> 318 <para> 319 gvfs contains a GConf-based implementation that uses the 320 same GConf keys as gnome-vfs. 321 </para> 322 </formalpara> 323 </chapter> 324 </part> 325
