← Back to branch summary

~ubuntu-branches/ubuntu/trusty/glib2.0/trusty-proposed

« back to all changes in this revision

Viewing changes to docs/reference/gio/xml/migrating.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2010-03-09 11:28:22 UTC
  • mfrom: (3.4.8 experimental)
  • Revision ID: james.westby@ubuntu.com-20100309112822-j4n0v3xbtsup8s97
Tags: 2.23.5-1ubuntu1
* Resync on Debian
* debian/patches/01_gettext-desktopfiles.patch:
  - updated to use gettext for X-GNOME-Fullname too
* debian/patches/71_gio_launch_handler.patch:
  - new gio default launch handle feature required for wncksync
* debian/control.in, 
  debian/patches/80-gtester-subunit.patch:
  - gtester-report subunit support
* debian/libglib2.0-0.symbols:
  - updated the symbols list for the gio launcher handler
* debian/rules:
  - don't break build on test suite errors, debian recently activated this but
    the build breaks even when there is no error in the testsuite

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/gio/xml/migrating.xml
 
1
<part id="migrating">
 
2
  <title>Migrating to GIO</title>
 
3
 
 
4
  <chapter>
 
5
    <title>Migrating from POSIX to GIO</title>
 
6
  
 
7
    <table id="posix-vs-gio">
 
8
      <title>Comparison of POSIX and GIO concepts</title>
 
9
      <tgroup cols="2">
 
10
        <thead>
 
11
          <row><entry>POSIX</entry><entry>GIO</entry></row>
 
12
        </thead>
 
13
        <tbody>
 
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>
 
22
        </tbody>
 
23
      </tgroup>
 
24
    </table>  
 
25
 
 
26
  </chapter>
 
27
 
 
28
  <chapter>
 
29
    <title>Migrating from GnomeVFS to GIO</title>
 
30
 
 
31
    <table id="gnome-vfs-vs-gio">
 
32
      <title>Comparison of GnomeVFS and GIO concepts</title>
 
33
      <tgroup cols="2">
 
34
        <thead>
 
35
          <row><entry>GnomeVFS</entry><entry>GIO</entry></row>
 
36
        </thead>
 
37
        <tbody>
 
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 &amp; 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>
 
51
        </tbody>
 
52
      </tgroup>
 
53
    </table>
 
54
 
 
55
    <section>
 
56
      <title>Trash handling</title>
 
57
 
 
58
      <para>
 
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.
 
68
      </para>
 
69
      <para>
 
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:
 
76
      </para>
 
77
<informalexample><programlisting>
 
78
static void
 
79
file_changed (GFileMonitor      *file_monitor,
 
80
              GFile             *child,
 
81
              GFile             *other_file,
 
82
              GFileMonitorEvent  event_type,
 
83
              gpointer           user_data)
 
84
{
 
85
  switch (event_type)
 
86
  {
 
87
  case G_FILE_MONITOR_EVENT_DELETED:
 
88
    g_print ("'%s' removed from trash\n", g_file_get_basename (child));
 
89
    break;
 
90
  case G_FILE_MONITOR_EVENT_CREATED:
 
91
    g_print ("'%s' added to trash\n", g_file_get_basename (child));
 
92
    break;
 
93
  default: ;
 
94
  }
 
95
}
 
96
 
 
97
static void
 
98
start_monitoring_trash (void)
 
99
{
 
100
  GFile *file;
 
101
  GFileMonitor *monitor;
 
102
 
 
103
  file = g_file_new_for_uri ("trash://");
 
104
  monitor = g_file_monitor_directory (file, 0, NULL, NULL);
 
105
  g_object_unref (file);
 
106
 
 
107
  g_signal_connect (monitor, "changed", G_CALLBACK (file_changed), NULL);
 
108
 
 
109
  /* ... */
 
110
 
 
111
}       
 
112
</programlisting></informalexample> 
 
113
      <para>
 
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.
 
121
      </para>
 
122
      <para>
 
123
        Moving a file to the trash is much simpler with GIO. Instead of
 
124
        using <link linkend="gnome-vfs-find-directory"><function>gnome_vfs_find_directory()</function></link> with <link linkend="GNOME-VFS-DIRECTORY-KIND-TRASH--CAPS"><literal>GNOME_VFS_DIRECTORY_KIND_TRASH</literal></link> 
 
125
        to find out where to move the trashed file, just use the <link linkend="g-file-trash"><function>g_file_trash()</function></link>
 
126
        function.
 
127
      </para>
 
128
    </section>
 
129
 
 
130
    <section>
 
131
      <title>Operations on multiple files</title>
 
132
 
 
133
      <para>
 
134
        gnome-vfs has the dreaded <link linkend="gnome-vfs-xfer-uri-list"><function>gnome_vfs_xfer_uri_list()</function></link> function which
 
135
        has tons of options and offers the equivalent of cp, mv, ln, mkdir
 
136
        and rm at the same time. 
 
137
      </para>
 
138
      <para>
 
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 <link linkend="g-io-scheduler-push-job"><function>g_io_scheduler_push_job()</function></link>. 
 
143
      </para>
 
144
 
 
145
    </section>
 
146
 
 
147
    <section>
 
148
      <title>Mime monitoring</title>
 
149
 
 
150
      <para>
 
151
        gnome-vfs offered a way to monitor the association between mime types
 
152
        and default handlers for changes, with the <link linkend="GnomeVFSMIMEMonitor"><type>GnomeVFSMIMEMonitor</type></link> 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
        <link linkend="GnomeVFSMIMEMonitor"><type>GnomeVFSMIMEMonitor</type></link> 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>.
 
158
      </para>
 
159
    </section>
 
160
  </chapter>
 
161
 
 
162
</part>