2 <title>Migrating to GIO</title>
5 <title>Migrating from POSIX to GIO</title>
7 <table id="posix-vs-gio">
8 <title>Comparison of POSIX and GIO concepts</title>
11 <row><entry>POSIX</entry><entry>GIO</entry></row>
14 <row><entry>char *path</entry><entry>GFile *file</entry></row>
15 <row><entry>struct stat *buf</entry><entry>GFileInfo *info</entry></row>
16 <row><entry>struct statvfs *buf</entry><entry>GFileInfo *info</entry></row>
17 <row><entry morerows="1">int fd</entry><entry>GInputStream *in</entry></row>
18 <row><entry>GOutputStream *out</entry></row>
19 <row><entry>DIR *</entry><entry>GFileEnumerator *enum</entry></row>
20 <row><entry>fstab entry</entry><entry>GUnixMountPoint *mount_point</entry></row>
21 <row><entry>mtab entry</entry><entry>GUnixMountEntry *mount_entry</entry></row>
29 <title>Migrating from GnomeVFS to GIO</title>
31 <table id="gnome-vfs-vs-gio">
32 <title>Comparison of GnomeVFS and GIO concepts</title>
35 <row><entry>GnomeVFS</entry><entry>GIO</entry></row>
38 <row><entry>GnomeVFSURI</entry><entry>GFile</entry></row>
39 <row><entry>GnomeVFSFileInfo</entry><entry>GFileInfo</entry></row>
40 <row><entry>GnomeVFSResult</entry><entry>GError, with G_IO_ERROR values</entry></row>
41 <row><entry>GnomeVFSHandle & GnomeVFSAsyncHandle</entry><entry>GInputStream or GOutputStream</entry></row>
42 <row><entry>GnomeVFSDirectoryHandle</entry><entry>GFileEnumerator</entry></row>
43 <row><entry>mime type</entry><entry>content type</entry></row>
44 <row><entry>GnomeVFSMonitor</entry><entry>GFileMonitor</entry></row>
45 <row><entry>GnomeVFSVolumeMonitor</entry><entry>GVolumeMonitor</entry></row>
46 <row><entry>GnomeVFSVolume</entry><entry>GMount</entry></row>
47 <row><entry>GnomeVFSDrive</entry><entry>GVolume</entry></row>
48 <row><entry>-</entry><entry>GDrive</entry></row>
49 <row><entry>GnomeVFSContext</entry><entry>GCancellable</entry></row>
50 <row><entry>gnome_vfs_async_cancel</entry><entry>g_cancellable_cancel</entry></row>
56 <title>Trash handling</title>
59 The handling of trashed files has been changed in GIO, compared
60 to gnome-vfs. gnome-vfs has a home-grown trash implementation that
61 predates the freedesktop.org <ulink url="http://www.freedesktop.org/wiki/Specifications/trash-spec">Desktop Trash Can</ulink> specification
62 that is implemented in GIO. The location for storing trashed files
63 has changed from <filename>$HOME/.Trash</filename> to
64 <filename>$HOME/.local/share/Trash</filename> (or more correctly
65 <filename>$XDG_DATA_HOME/Trash</filename>), which means that
66 there is a need for migrating files that have been trashed by
67 gnome-vfs to the new location.
70 In gnome-vfs, the <filename>trash://</filename> scheme offering a
71 merged view of all trash directories was implemented in nautilus,
72 and trash-handling applications had to find and monitor all trash
73 directories themselves. With GIO, the <filename>trash://</filename>
74 implementation has been moved to gvfs and applications can simply
75 monitor that location:
77 <informalexample><programlisting>
79 file_changed (GFileMonitor *file_monitor,
82 GFileMonitorEvent event_type,
87 case G_FILE_MONITOR_EVENT_DELETED:
88 g_print ("'%s' removed from trash\n", g_file_get_basename (child));
90 case G_FILE_MONITOR_EVENT_CREATED:
91 g_print ("'%s' added to trash\n", g_file_get_basename (child));
98 start_monitoring_trash (void)
101 GFileMonitor *monitor;
103 file = g_file_new_for_uri ("trash://");
104 monitor = g_file_monitor_directory (file, 0, NULL, NULL);
105 g_object_unref (file);
107 g_signal_connect (monitor, "changed", G_CALLBACK (file_changed), NULL);
112 </programlisting></informalexample>
114 GIO exposes some useful metadata about trashed files. There are
115 trash::orig-path and trash::deletion-date attributes. The
116 standard::icon attribute of the <filename>trash://</filename>
117 itself provides a suitable icon for displaying the trash can on
118 the desktop. If you are using this icon, make sure to monitor
119 this attribute for changes, since the icon may be updated to
120 reflect that state of the trash can.
123 Moving a file to the trash is much simpler with GIO. Instead of
124 using gnome_vfs_find_directory() with %GNOME_VFS_DIRECTORY_KIND_TRASH
125 to find out where to move the trashed file, just use the g_file_trash()
131 <title>Operations on multiple files</title>
134 gnome-vfs has the dreaded gnome_vfs_xfer_uri_list() function which
135 has tons of options and offers the equivalent of cp, mv, ln, mkdir
136 and rm at the same time.
139 GIO offers a much simpler I/O scheduler functionality instead, that
140 lets you schedule a function to be called in a separate thread, or
141 if threads are not available, as an idle in the mainloop.
142 See g_io_scheduler_push_job().
148 <title>Mime monitoring</title>
151 gnome-vfs offered a way to monitor the association between mime types
152 and default handlers for changes, with the #GnomeVFSMIMEMonitor object.
153 GIO does not offer a replacement for this functionality at this time,
154 since we have not found a compelling use case where
155 #GnomeVFSMIMEMonitor was used. If you think you have such a use
156 case, please report it at
157 <ulink url="http://bugzilla.gnome.org">bugzilla.gnome.org</ulink>.