Session Management

Using the GnomeClient Object

Gnome shields you from the raw session management interface that comes with X. This is done via a GtkObject called GnomeClient. GnomeClient represents your application's connection to the session manager.

Gnome manages most of the details of session management. For most applications, you only have to respond to two requests.

• When a session is saved, the session manager will ask each client to save enough information to restore its state the next time the user logs in. Your application should save as much interesting state as possible: the current open documents, cursor position, command histories, and so on. Applications should not save their current window geometries; the window manager is responsible for that.

• Sometimes the session manager will ask your client to shut down and exit (typically when the user logs out). When you receive this request you should do whatever is necessary to exit the application.

When the session manager requests action from your application, a the GnomeClient object emits an appropriate signal. The two important signals are "save_yourself" and "die". "save_yourself" is emitted when an application should save its state, and "die" is emitted when an application should exit. A "save_yourself" callback is fairly complex and has quite a few arguments; a "die" callback is trivial.

GnomeHello obtains a pointer to the GnomeClient object and connects to its signals as follows:

  client = gnome_master_client ();
  gtk_signal_connect (GTK_OBJECT (client), "save_yourself",
                      GTK_SIGNAL_FUNC (save_session), argv[0]);
  gtk_signal_connect (GTK_OBJECT (client), "die",
                      GTK_SIGNAL_FUNC (session_die), NULL);

argv[0] will be used in the "save_yourself" callback.

First, here's the "die" callback from GnomeHello:

static void
session_die(GnomeClient* client, gpointer client_data)
{
  gtk_main_quit ();
}

Straightforward; the application just exits.

Now the "save_yourself" callback:

static gint
save_session (GnomeClient *client, gint phase, GnomeSaveStyle save_style,
              gint is_shutdown, GnomeInteractStyle interact_style,
              gint is_fast, gpointer client_data)
{
  gchar** argv;
  guint argc;

  /* allocate 0-filled, so it will be NULL-terminated */
  argv = g_malloc0(sizeof(gchar*)*4);
  argc = 1;

  argv[0] = client_data;

  if (message)
    {
      argv[1] = "--message";
      argv[2] = message;
      argc = 3;
    }
  
  gnome_client_set_clone_command (client, argc, argv);
  gnome_client_set_restart_command (client, argc, argv);

  return TRUE;
}

This is a bit more complex. A "save_yourself" must tell the session manager how to restart and "clone" (create a new instance of) the application. The restarted application should remember as much state as possible; in GnomeHello's case, it will remember the message being displayed. The simplest way to store application state is to generate a command line, as GnomeHello does. It's also possible to ask GnomeClient for a prefix to be used with the gnome-config API; you can then save information to a per-session configuration file. Applications with significant state will need to use this method.