GnomeClient

GnomeClient

Functions

#define GNOME_CLIENT_CONNECTED()
void (*GnomeInteractFunction) ()
GnomeClient * gnome_master_client ()
const gchar * gnome_client_get_config_prefix ()
const gchar * gnome_client_get_global_config_prefix ()
const GnomeModuleInfo * gnome_client_module_info_get ()
void gnome_client_set_global_config_prefix ()
GnomeClientFlags gnome_client_get_flags ()
void gnome_client_set_restart_style ()
void gnome_client_set_priority ()
void gnome_client_set_restart_command ()
void gnome_client_add_static_arg ()
void gnome_client_set_discard_command ()
void gnome_client_set_resign_command ()
void gnome_client_set_shutdown_command ()
void gnome_client_set_current_directory ()
void gnome_client_set_environment ()
void gnome_client_set_clone_command ()
void gnome_client_set_process_id ()
void gnome_client_set_program ()
void gnome_client_set_user_id ()
void gnome_client_save_any_dialog ()
void gnome_client_save_error_dialog ()
void gnome_client_request_phase_2 ()
void gnome_client_request_save ()
void gnome_client_flush ()
void gnome_client_disable_master_connection ()
GnomeClient * gnome_client_new ()
GnomeClient * gnome_client_new_without_connection ()
void gnome_client_connect ()
void gnome_client_disconnect ()
void gnome_client_set_id ()
const gchar * gnome_client_get_id ()
const gchar * gnome_client_get_previous_id ()
const gchar * gnome_client_get_desktop_id ()
void gnome_client_request_interaction ()
void gnome_client_request_interaction_interp ()
void gnome_interaction_key_return ()

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkObject
            ╰── GnomeClient

Includes

#include <libgnomeui/libgnomeui.h>

Description

Functions

GNOME_CLIENT_CONNECTED()

#define GNOME_CLIENT_CONNECTED(obj) (GNOME_CLIENT (obj)->smc_conn)

GnomeInteractFunction ()

void
(*GnomeInteractFunction) (GnomeClient *client,
                          gint key,
                          GnomeDialogType dialog_type,
                          gpointer data);

gnome_master_client ()

GnomeClient *
gnome_master_client (void);

Get the master session management client. This master client gets a client id, that may be specified by the '--sm-client-id' command line option. A master client will be generated by gnome_program_init(). If possible the master client will contact the session manager after command-line parsing is finished (unless gnome_client_disable_master_connection() was called). The master client will also set the SM_CLIENT_ID property on the client leader window of your application.

Additionally, the master client gets some static arguments set automatically (see gnome_client_add_static_arg() for static arguments): gnome_program_init() passes all the command line options which are recognised by gtk as static arguments to the master client.

Returns

Pointer to the master client


gnome_client_get_config_prefix ()

const gchar *
gnome_client_get_config_prefix (GnomeClient *client);

Get the config prefix for a client. This config prefix provides a suitable place to store any details about the state of the client which can not be described using the app's command line arguments (as set in the restart command). You may push the returned value using gnome_config_push_prefix() and read or write any values you require.

Parameters

client

Pointer to GNOME session client object.

 

Returns

Config prefix. The returned string belongs to libgnomeui library and should NOT be freed by the caller.


gnome_client_get_global_config_prefix ()

const gchar *
gnome_client_get_global_config_prefix (GnomeClient *client);

Get the config prefix that will be returned by gnome_client_get_config_prefix() for clients which have NOT been restarted or cloned (i.e. for clients started by the user without `--sm-' options). This config prefix may be used to write the user's preferred config for these "new" clients.

You could also use this prefix as a place to store and retrieve config details that you wish to apply to ALL instances of the app. However, this practice limits the users freedom to configure each instance in a different way so it should be used with caution.

Parameters

client

Pointer to GNOME session client object.

 

Returns

The config prefix as a newly allocated string.


gnome_client_module_info_get ()

const GnomeModuleInfo *
gnome_client_module_info_get (void);

gnome_client_set_global_config_prefix ()

void
gnome_client_set_global_config_prefix (GnomeClient *client,
                                       const gchar *prefix);

Set the value used for the global config prefix. The config prefixes returned by gnome_client_get_config_prefix() are formed by extending this prefix with an unique identifier.

The global config prefix defaults to a name based on the name of the executable. This function allows you to set it to a different value. It should be called BEFORE retrieving the config prefix for the first time. Later calls will be ignored.

For example, setting a global config prefix of "/app.d/session/" would ensure that all your session save files or directories would be gathered together into the app.d directory.

Parameters

client

Pointer to GNOME session client object.

 

prefix

Prefix for saving the global configuration.

 

gnome_client_get_flags ()

GnomeClientFlags
gnome_client_get_flags (GnomeClient *client);

Determine the client's status with the session manager.,

Parameters

client

Pointer to GNOME session client object.

 

Returns

Various GnomeClientFlag flags which have been or'd together.


gnome_client_set_restart_style ()

void
gnome_client_set_restart_style (GnomeClient *client,
                                GnomeRestartStyle style);

Tells the session manager how the client should be restarted in future session. The options are given by the GnomeRestartStyle enum.

Parameters

client

Pointer to GNOME session client object.

 

style

When to restart the client.

 

gnome_client_set_priority ()

void
gnome_client_set_priority (GnomeClient *client,
                           guint priority);

The gnome-session manager restarts clients in order of their priorities in a similar way to the start up ordering in SysV. This function allows the app to suggest a position in this ordering. The value should be between 0 and 99. A default value of 50 is assigned to apps that do not provide a value. The user may assign a different priority.

Parameters

client

Pointer to GNOME session client object.

 

priority

Position of client in session start up ordering.

 

gnome_client_set_restart_command ()

void
gnome_client_set_restart_command (GnomeClient *client,
                                  gint argc,
                                  gchar *argv[]);

When clients crash or the user logs out and back in, they are restarted. This command should perform the restart. Executing the restart command on the local host should reproduce the state of the client at the time of the session save as closely as possible. Saving config info under the gnome_client_get_config_prefix() is generally useful.

Parameters

client

Pointer to GNOME session client object.

 

argc

Number of strings in argv.

 

argv

Argument vector to an execv() to restart the client.

 

gnome_client_add_static_arg ()

void
gnome_client_add_static_arg (GnomeClient *client,
                             ...);

You can add arguments to your restart command's argv with this function. This function provides an alternative way of adding new arguments to the restart command. The arguments are placed before the arguments specified by gnome_client_set_restart_command() and after the arguments recognised by GTK+ that are specified by the user on the original command line.

Parameters

client

Pointer to GNOME session client object.

 

...

NULL-terminated list of arguments to add to the restart command.

 

gnome_client_set_discard_command ()

void
gnome_client_set_discard_command (GnomeClient *client,
                                  gint argc,
                                  gchar *argv[]);

gnome_client_set_resign_command ()

void
gnome_client_set_resign_command (GnomeClient *client,
                                 gint argc,
                                 gchar *argv[]);

Some clients can be "undone," removing their effects and deleting any saved state. For example, xmodmap could register a resign command to undo the keymap changes it saved.

Used by clients that use the GNOME_RESTART_ANYWAY restart style to to undo their effects (these clients usually perform initialisation functions and leave effects behind after they die). The resign command combines the effects of a shutdown command and a discard command. It is executed when the user decides that the client should cease to be restarted.

Parameters

client

Pointer to GNOME session client object.

 

argc

Number of strings in argv .

 

argv

execv()-style command to undo the effects of the client.

 

gnome_client_set_shutdown_command ()

void
gnome_client_set_shutdown_command (GnomeClient *client,
                                   gint argc,
                                   gchar *argv[]);

GNOME_RESTART_ANYWAY clients can set this command to run when the user logs out but the client is no longer running.

Used by clients that use the GNOME_RESTART_ANYWAY restart style to to undo their effects (these clients usually perform initialisation functions and leave effects behind after they die). The shutdown command simply undoes the effects of the client. It is executed during a normal logout.

Parameters

client

Pointer to GNOME session client object.

 

argc

Number of strings in argv.

 

argv

Command to shutdown the client if the client isn't running.

 

gnome_client_set_current_directory ()

void
gnome_client_set_current_directory (GnomeClient *client,
                                    const gchar *dir);

Set the directory to be in when running shutdown, discard, restart, etc. commands.

Parameters

client

Pointer to GNOME session client object.

 

dir

Directory path.

 

gnome_client_set_environment ()

void
gnome_client_set_environment (GnomeClient *client,
                              const gchar *name,
                              const gchar *value);

Set an environment variable to be placed in the client's environment prior to running restart, shutdown, discard, etc. commands.

Parameters

client

Pointer to GNOME session client object.

 

name

Name of the environment variable

 

value

Value of the environment variable

 

gnome_client_set_clone_command ()

void
gnome_client_set_clone_command (GnomeClient *client,
                                gint argc,
                                gchar *argv[]);

Set a command the session manager can use to create a new instance of the application.

Parameters

client

Pointer to GNOME session client object.

 

argc

Number of strings in the argv vector.

 

argv

Argument strings, suitable for use with execv().

 

gnome_client_set_process_id ()

void
gnome_client_set_process_id (GnomeClient *client,
                             pid_t pid);

The client should tell the session manager the result of getpid(). However, GNOME does this automatically; so you do not need this function.

Parameters

client

Pointer to GNOME session client object.

 

pid

PID to set as the client's PID.

 

gnome_client_set_program ()

void
gnome_client_set_program (GnomeClient *client,
                          const gchar *program);

Used to tell the session manager the name of your program. Set automatically; this function isn't needed.

Parameters

client

Pointer to GNOME session client object.

 

program

Name of the program.

 

gnome_client_set_user_id ()

void
gnome_client_set_user_id (GnomeClient *client,
                          const gchar *id);

Tell the session manager the user's login name. GNOME does this automatically; no need to call the function.

Parameters

client

Pointer to GNOME session client object.

 

id

Username.

 

gnome_client_save_any_dialog ()

void
gnome_client_save_any_dialog (GnomeClient *client,
                              GtkDialog *dialog);

May be called during a "save_youself" handler to request that a (modal) dialog is presented to the user. The session manager decides when the dialog is shown, but it will not be shown it unless the session manager is sending an interaction style of GNOME_INTERACT_ANY. A "Cancel Logout" button will be added during a shutdown.

Parameters

client

Pointer to GnomeClient object.

 

dialog

Pointer to GNOME dialog widget (a GtkDialog widget).

 

gnome_client_save_error_dialog ()

void
gnome_client_save_error_dialog (GnomeClient *client,
                                GtkDialog *dialog);

May be called during a "save_youself" handler when an error has occurred during the save. The session manager decides when the dialog is shown, but it will not be shown it unless the session manager is sending an interaction style of GNOME_INTERACT_ANY. A "Cancel Logout" button will be added during a shutdown.

Parameters

client

Pointer to GnomeClient object.

 

dialog

Pointer to GNOME dialog widget (a GtkDialog widget).

 

gnome_client_request_phase_2 ()

void
gnome_client_request_phase_2 (GnomeClient *client);

Request the session managaer to emit the "save_yourself" signal for a second time after all the clients in the session have ceased interacting with the user and entered an idle state. This might be useful if your app manages other apps and requires that they are in an idle state before saving its final data.

Parameters

client

A GnomeClient object.

 

gnome_client_request_save ()

void
gnome_client_request_save (GnomeClient *client,
                           GnomeSaveStyle save_style,
                           gboolean shutdown,
                           GnomeInteractStyle interact_style,
                           gboolean fast,
                           gboolean global);

Request the session manager to save the session in some way. The arguments correspond with the arguments passed to the "save_yourself" signal handler.

The save_style indicates whether the save should affect data accessible to other users (GNOME_SAVE_GLOBAL) or only the state visible to the current user (GNOME_SAVE_LOCAL) or both. Setting shutdown to TRUE will initiate a logout. The interact_style specifies which kinds of interaction will be available. Setting fast to TRUE will limit the save to setting the session manager properties plus any essential data. Setting the value of global to TRUE will request that all the other apps in the session do a save as well. A global save is mandatory when doing a shutdown.

Parameters

client

Pointer to GNOME session client object.

 

save_style

Save style to request.

 

shutdown

Whether to log out of the session.

 

interact_style

Whether to allow user interaction.

 

fast

Minimize activity to save as soon as possible.

 

global

Request that all other apps in the session also save their state.

 

gnome_client_flush ()

void
gnome_client_flush (GnomeClient *client);

This will force the underlying connection to the session manager to be flushed. This is useful if you have some pending changes that you want to make sure get committed.

Parameters

client

A GnomeClient instance.

 

gnome_client_disable_master_connection ()

void
gnome_client_disable_master_connection
                               (void);

gnome_client_disable_master_connection is deprecated and should not be used in newly-written code.

Don't connect the master client to the session manager. Usually invoked by users when they pass the --sm-disable argument to a Gnome application.


gnome_client_new ()

GnomeClient *
gnome_client_new (void);

gnome_client_new is deprecated and should not be used in newly-written code.

Allocates memory for a new GNOME session management client object. After allocating, the client tries to connect to a session manager. You probably want to use gnome_master_client() instead.

Returns

Pointer to a newly allocated GNOME session management client object.


gnome_client_new_without_connection ()

GnomeClient *
gnome_client_new_without_connection (void);

Allocates memory for a new GNOME session management client object. You probably want to use gnome_master_client() instead.

Returns

Pointer to a newly allocated GNOME session management client object.


gnome_client_connect ()

void
gnome_client_connect (GnomeClient *client);

Causes the client to connect to the session manager. Usually happens automatically; no need to call this function.

Parameters

client

A GnomeClient instance.

 

gnome_client_disconnect ()

void
gnome_client_disconnect (GnomeClient *client);

Disconnect the client from the session manager.

Parameters

client

A GnomeClient instance.

 

gnome_client_set_id ()

void
gnome_client_set_id (GnomeClient *client,
                     const gchar *id);

Set the client's session management ID; must be done before connecting to the session manager. There is usually no reason to call this function.

Parameters

client

A GnomeClient instance.

 

id

Session management ID.

 

gnome_client_get_id ()

const gchar *
gnome_client_get_id (GnomeClient *client);

Returns session management ID

Parameters

client

A GnomeClient instance.

 

Returns

Session management ID for this client; NULL if not connected to a session manager.


gnome_client_get_previous_id ()

const gchar *
gnome_client_get_previous_id (GnomeClient *client);

Get the session management ID from the previous session.

Parameters

client

A GnomeClient instance.

 

Returns

Pointer to the session management ID the client had in the last session, or NULL if it was not in a previous session.


gnome_client_get_desktop_id ()

const gchar *
gnome_client_get_desktop_id (GnomeClient *client);

Get the client ID of the desktop's current instance, i.e. if you consider the desktop as a whole as a session managed app, this returns its session ID using a GNOME extension to session management. May return NULL for apps not running under a recent version of gnome-session; apps should handle that case.

Parameters

client

A GnomeClient instance.

 

Returns

Session ID of GNOME desktop instance, or NULL if none.


gnome_client_request_interaction ()

void
gnome_client_request_interaction (GnomeClient *client,
                                  GnomeDialogType dialog_type,
                                  GnomeInteractFunction function,
                                  gpointer data);

Use the following functions, if you want to interact with the user during a "save_yourself" handler without being restricted to using the dialog based commands gnome_client_save_any_dialog() or gnome_client_save_error_dialog(). Note, however, that overriding the session manager specified preference in this way (by using arbitrary dialog boxes) is not very nice.

If and when the session manager decides that it's the app's turn to interact then 'func' will be called with the specified arguments and a unique 'GnomeInteractionKey'. The session manager will block other clients from interacting until this key is returned with gnome_interaction_key_return().

Parameters

client

A GnomeClient object.

 

dialog_type

The type of dialog to create.

 

function

Callback to invoke to perform the interaction.

 

data

Callback data.

 

gnome_client_request_interaction_interp ()

void
gnome_client_request_interaction_interp
                               (GnomeClient *client,
                                GnomeDialogType dialog_type,
                                GtkCallbackMarshal function,
                                gpointer data,
                                GDestroyNotify destroy);

Similar to gnome_client_request_interaction(), but used when you need to destroy the callback data after the interaction.

Parameters

client

Pointer to GNOME session client object.

 

dialog_type

Type of dialog to show.

 

function

Callback to perform the interaction (a GnomeInteractFunction).

 

data

Callback data.

 

destroy

Function to destroy callback data.

 

gnome_interaction_key_return ()

void
gnome_interaction_key_return (gint key,
                              gboolean cancel_shutdown);

Used in interaction callback to tell the session manager you are done interacting.

Parameters

key

Key passed to interaction callback

 

cancel_shutdown

If TRUE, cancel the shutdown

 

Types and Values

enum GnomeDialogType

Members

GNOME_DIALOG_ERROR

   

GNOME_DIALOG_NORMAL

   

enum GnomeRestartStyle

Members

GNOME_RESTART_IF_RUNNING

   

GNOME_RESTART_ANYWAY

   

GNOME_RESTART_IMMEDIATELY

   

GNOME_RESTART_NEVER

   

enum GnomeClientFlags

Members

GNOME_CLIENT_IS_CONNECTED

   

GNOME_CLIENT_RESTARTED

   

GNOME_CLIENT_RESTORED

   

enum GnomeSaveStyle

Members

GNOME_SAVE_GLOBAL

   

GNOME_SAVE_LOCAL

   

GNOME_SAVE_BOTH

   

enum GnomeInteractStyle

Members

GNOME_INTERACT_NONE

   

GNOME_INTERACT_ERRORS

   

GNOME_INTERACT_ANY

   

struct GnomeClient

struct GnomeClient;

GNOME_CLIENT_PARAM_SM_CONNECT

#define GNOME_CLIENT_PARAM_SM_CONNECT "sm-connect"

Signal Details

The “connect” signal

void
user_function (GnomeClient *client,
               gboolean     arg1,
               gpointer     user_data)

Flags: Run First


The “die” signal

void
user_function (GnomeClient *client,
               gpointer     user_data)

Flags: Run Last


The “disconnect” signal

void
user_function (GnomeClient *client,
               gpointer     user_data)

Flags: Run First


The “save-complete” signal

void
user_function (GnomeClient *client,
               gpointer     user_data)

Flags: Run First


The “save-yourself” signal

gboolean
user_function (GnomeClient       *client,
               gint               arg1,
               GnomeSaveStyle     arg2,
               gboolean           arg3,
               GnomeInteractStyle arg4,
               gboolean           arg5,
               gpointer           user_data)

Flags: Run Last


The “shutdown-cancelled” signal

void
user_function (GnomeClient *client,
               gpointer     user_data)

Flags: Run First