| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>Data conversion: GIO Reference Manual</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
| <link rel="home" href="index.html" title="GIO Reference Manual"> |
| <link rel="up" href="ch34.html" title="Migrating from GConf to GSettings"> |
| <link rel="prev" href="ch34s06.html" title="Schema conversion"> |
| <link rel="next" href="ch35.html" title="Migrating to GDBus"> |
| <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> |
| <td width="100%" align="left" class="shortcuts"></td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> |
| <td><a accesskey="u" href="ch34.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> |
| <td><a accesskey="p" href="ch34s06.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> |
| <td><a accesskey="n" href="ch35.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="section"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="id-1.5.4.8"></a>Data conversion</h2></div></div></div> |
| <p> |
| GConf comes with a GSettings backend that can be used to |
| facility the transition to the GSettings API until you are |
| ready to make the jump to a different backend (most likely |
| dconf). To use it, you need to set the <code class="envar">GSETTINGS_BACKEND</code> |
| to 'gconf', e.g. by using |
| </p> |
| <pre class="programlisting"> |
| g_setenv ("GSETTINGS_BACKEND", "gconf", TRUE); |
| </pre> |
| <p> |
| early on in your program. Note that this backend is meant purely |
| as a transition tool, and should not be used in production. |
| </p> |
| <p> |
| GConf also comes with a utility called |
| <span class="command"><strong>gsettings-data-convert</strong></span>, which is designed to help |
| with the task of migrating user settings from GConf into another |
| GSettings backend. It can be run manually, but it is designed to be |
| executed automatically, every time a user logs in. It keeps track of |
| the data migrations that it has already done, and it is harmless to |
| run it more than once. |
| </p> |
| <p> |
| To make use of this utility, you must install a keyfile in the |
| directory <code class="filename">/usr/share/GConf/gsettings</code> which |
| lists the GSettings keys and GConf paths to map to each other, for |
| each schema that you want to migrate user data for. |
| </p> |
| <p> |
| Here is an example: |
| </p> |
| <pre class="programlisting"> |
| |
| [org.gnome.fonts] |
| antialiasing = /desktop/gnome/font_rendering/antialiasing |
| dpi = /desktop/gnome/font_rendering/dpi |
| hinting = /desktop/gnome/font_rendering/hinting |
| rgba-order = /desktop/gnome/font_rendering/rgba_order |
| |
| [apps.myapp:/path/to/myapps/] |
| some-odd-key1 = /apps/myapp/some_ODD-key1 |
| |
| </pre> |
| <p> |
| The last key demonstrates that it may be necessary to modify the key |
| name to comply with stricter GSettings key name rules. Of course, |
| that means your application must use the new key names when looking |
| up settings in GSettings. |
| </p> |
| <p> |
| The last group in the example also shows how to handle the case |
| of 'relocatable' schemas, which don't have a fixed path. You can |
| specify the path to use in the group name, separated by a colon. |
| </p> |
| <p> |
| There are some limitations: <span class="command"><strong>gsettings-data-convert</strong></span> |
| does not do any transformation of the values. And it does not handle |
| complex GConf types other than lists of strings or integers. |
| </p> |
| <p> |
| Don't forget to require GConf 2.31.1 or newer in your configure |
| script if you are making use of the GConf backend or the conversion |
| utility. |
| </p> |
| <p> |
| If, as an application developer, you are interested in manually |
| ensuring that <span class="command"><strong>gsettings-data-convert</strong></span> 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. |
| </p> |
| <p> |
| Internally, <span class="command"><strong>gsettings-data-convert</strong></span> 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. |
| </p> |
| <p> |
| </p> |
| <pre class="programlisting"> |
| |
| 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); |
| } |
| |
| |
| </pre> |
| <p> |
| </p> |
| <p> |
| Although there is the possibility that the |
| <span class="command"><strong>gsettings-data-convert</strong></span> script will end up |
| running multiple times concurrently with this approach, it is |
| believed that this is safe. |
| </p> |
| </div> |
| <div class="footer"> |
| <hr>Generated by GTK-Doc V1.25.1</div> |
| </body> |
| </html> |
