script if you are making use of the GConf backend or the conversion
utility.
</para>
+
+ <para>
+ If, as an application developer, you are interested in manually
+ ensuring that <command>gsettings-data-convert</command> has been
+ invoked (for example, to deal with the case where the user is
+ logged in during a distribution upgrade or for non-XDG desktop
+ environments which do not run the command as an autostart) you
+ may invoke it manually during your program initialisation. This
+ is not recommended for all application authors -- it is your
+ choice if this use case concerns you enough.
+ </para>
+ <para>
+ Internally, <command>gsettings-data-convert</command> uses a
+ keyfile to track which settings have been migrated. The
+ following code fragment will check that keyfile to see if your
+ data conversion script has been run yet and, if not, will
+ attempt to invoke the tool to run it. You should adapt it to
+ your application as you see fit.
+ </para>
+ <para>
+ <programlisting>
+<![CDATA[
+static void
+ensure_migrated (const gchar *name)
+{
+ gboolean needed = TRUE;
+ GKeyFile *kf;
+ gchar **list;
+ gsize i, n;
+
+ kf = g_key_file_new ();
+
+ g_key_file_load_from_data_dirs (kf, "gsettings-data-convert",
+ NULL, G_KEY_FILE_NONE, NULL);
+ list = g_key_file_get_string_list (kf, "State", "converted", &n, NULL);
+
+ if (list)
+ {
+ for (i = 0; i < n; i++)
+ if (strcmp (list[i], name) == 0)
+ {
+ needed = FALSE;
+ break;
+ }
+
+ g_strfreev (list);
+ }
+
+ g_key_file_free (kf);
+
+ if (needed)
+ g_spawn_command_line_sync ("gsettings-data-convert",
+ NULL, NULL, NULL, NULL);
+}
+
+]]>
+ </programlisting>
+ </para>
+ <para>
+ Although there is the possibility that the
+ <command>gsettings-data-convert</command> script will end up
+ running multiple times concurrently with this approach, it is
+ believed that this is safe.
+ </para>
</section>
</chapter>