Gnome User Interface Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GnomeClient

## Name

GnomeClient -- Routines to provide session management support in your application

## Synopsis

    #include <gnome.h>

    struct      GnomeClient;
    enum        GnomeClientFlags;
    #define     GNOME_CLIENT_CONNECTED          (obj)
    enum        GnomeInteractStyle;
    enum        GnomeDialogType;
    enum        GnomeSaveStyle;
    enum        GnomeRestartStyle;
    enum        GnomeClientState;
    void        (*GnomeInteractFunction)        (GnomeClient *client,
                                                 gint key,
                                                 GnomeDialogType dialog_type,
                                                 gpointer data);
    void        gnome_client_disable_master_connection
                                                (void);
    GnomeClient* gnome_master_client            (void);
    GnomeClient* gnome_cloned_client            (void);
    GnomeClient* gnome_client_new               (void);
    GnomeClient* gnome_client_new_without_connection
                                                (void);
    void        gnome_client_connect            (GnomeClient *client);
    void        gnome_client_disconnect         (GnomeClient *client);
    void        gnome_client_set_id             (GnomeClient *client,
                                                 const gchar *client_id);
    gchar*      gnome_client_get_id             (GnomeClient *client);
    gchar*      gnome_client_get_previous_id    (GnomeClient *client);
    gchar*      gnome_client_get_config_prefix  (GnomeClient *client);
    gchar*      gnome_client_get_global_config_prefix
                                                (GnomeClient *client);
    void        gnome_client_set_global_config_prefix
                                                (GnomeClient *client,
                                                 gchar *prefix);
    GnomeClientFlags gnome_client_get_flags     (GnomeClient *client);
    void        gnome_client_set_restart_style  (GnomeClient *client,
                                                 GnomeRestartStyle style);
    void        gnome_client_set_restart_command
                                                (GnomeClient *client,
                                                 gint argc,
                                                 gchar *argv[]);
    void        gnome_client_add_static_arg     (GnomeClient *client,
                                                 ...);
    void        gnome_client_set_discard_command
                                                (GnomeClient *client,
                                                 gint argc,
                                                 gchar *argv[]);
    void        gnome_client_set_resign_command (GnomeClient *client,
                                                 gint argc,
                                                 gchar *argv[]);
    void        gnome_client_set_shutdown_command
                                                (GnomeClient *client,
                                                 gint argc,
                                                 gchar *argv[]);
    void        gnome_client_set_current_directory
                                                (GnomeClient *client,
                                                 const gchar *dir);
    void        gnome_client_set_environment    (GnomeClient *client,
                                                 const gchar *name,
                                                 const gchar *value);
    void        gnome_client_set_clone_command  (GnomeClient *client,
                                                 gint argc,
                                                 gchar *argv[]);
    void        gnome_client_set_process_id     (GnomeClient *client,
                                                 pid_t pid);
    void        gnome_client_set_program        (GnomeClient *client,
                                                 const gchar *program);
    void        gnome_client_set_user_id        (GnomeClient *client,
                                                 const gchar *user_id);
    void        gnome_client_request_phase_2    (GnomeClient *client);
    void        gnome_client_save_any_dialog    (GnomeClient *client,
                                                 GnomeDialog *dialog);
    void        gnome_client_save_error_dialog  (GnomeClient *client,
                                                 GnomeDialog *dialog);
    void        gnome_client_request_interaction
                                                (GnomeClient *client,
                                                 GnomeDialogType dialog,
                                                 GnomeInteractFunction func,
                                                 gpointer client_data);
    void        gnome_client_request_interaction_interp
                                                (GnomeClient *client,
                                                 GnomeDialogType dialog,
                                                 GtkCallbackMarshal func,
                                                 gpointer data,
                                                 GtkDestroyNotify destroy);
    void        gnome_interaction_key_return    (gint key,
                                                 gboolean cancel_shutdown);
    void        gnome_client_request_save       (GnomeClient *client,
                                                 GnomeSaveStyle save_style,
                                                 gboolean shutdown,
                                                 GnomeInteractStyle interact_style,
                                                 gboolean fast,
                                                 gboolean global);
    void        gnome_client_flush              (GnomeClient *client);
    void        gnome_client_init               (void);

## Object Hierarchy

      GtkObject
       +----GnomeClient

## Description

The GNOME project uses a special object - the GnomeClient object - to implement session management. This object handles the connection to a session manager, the setting and removing of properties and the handling of messages sent by a session manager.

There are two functions in the GNOME libraries, that create a new GnomeClient object: gnome_client_new() and gnome_client_new_without_connection(). As one may guess from the functions names: The first function tries to connect to a session manager automatically, while the second one does not. However, you probably don't need to create your own client; `gnome_init()` automatically creates a client for you. To obtain this client, call `gnome_master_client().`

Two useful sources of information on session management are the gnome-client header file and the SMlib.PS.Z document that comes with X.

## Details

### struct GnomeClient

    struct GnomeClient;

### enum GnomeClientFlags

    typedef enum
    {
      GNOME_CLIENT_IS_CONNECTED= 1 << 0,
      GNOME_CLIENT_RESTARTED   = 1 << 1,
      GNOME_CLIENT_RESTORED    = 1 << 2
    } GnomeClientFlags;

### GNOME_CLIENT_CONNECTED()

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

Returns TRUE if the client is connected to the session manager.

`obj` : | Client to check.

### enum GnomeInteractStyle

    typedef enum
    {
      GNOME_INTERACT_NONE,
      GNOME_INTERACT_ERRORS,
      GNOME_INTERACT_ANY
    } GnomeInteractStyle;

Controls permitted user interaction during session save.

### enum GnomeDialogType

    typedef enum
    {
      GNOME_DIALOG_ERROR,
      GNOME_DIALOG_NORMAL
    } GnomeDialogType;

Controls type of dialog generated for user interaction.

### enum GnomeSaveStyle

    typedef enum
    {
      GNOME_SAVE_GLOBAL,
      GNOME_SAVE_LOCAL,
      GNOME_SAVE_BOTH
    } GnomeSaveStyle;

### enum GnomeRestartStyle

    typedef enum
    {
      GNOME_RESTART_IF_RUNNING,
      GNOME_RESTART_ANYWAY,
      GNOME_RESTART_IMMEDIATELY,
      GNOME_RESTART_NEVER
    } GnomeRestartStyle;

### enum GnomeClientState

    typedef enum
    {
      GNOME_CLIENT_IDLE,
      GNOME_CLIENT_SAVING_PHASE_1,
      GNOME_CLIENT_WAITING_FOR_PHASE_2,
      GNOME_CLIENT_SAVING_PHASE_2,
      GNOME_CLIENT_FROZEN,
      GNOME_CLIENT_DISCONNECTED,
      GNOME_CLIENT_REGISTERING
    } GnomeClientState;

### GnomeInteractFunction ()

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

Callback invoked to perform user interaction.

`client` : | Client.
`key` : | Key to be returned when interaction ends.
`dialog_type` : | Type of dialog being shown.
`data` : | Callback data.

### gnome_client_disable_master_connection ()

    void        gnome_client_disable_master_connection
                                                (void);

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_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-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_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_cloned_client ()

    GnomeClient* gnome_cloned_client            (void);

Returns : | Pointer to

### gnome_client_new ()

    GnomeClient* gnome_client_new               (void);

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 <function>gnome_master_client()</function> 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 <function>gnome_master_client()</function> 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.

`client` : | Pointer to GNOME session client object.

### gnome_client_disconnect ()

    void        gnome_client_disconnect         (GnomeClient *client);

Disconnect the client from the session manager.

`client` : | Pointer to GNOME session client object.

### gnome_client_set_id ()

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

Set the client's session management ID; must be done before connecting to the session manager. Frankly I have no idea why you'd do this.

`client` : | Pointer to GNOME session client object.
`client_id` : |

### gnome_client_get_id ()

    gchar*      gnome_client_get_id             (GnomeClient *client);

Returns session management ID

`client` : | Pointer to GNOME session client object.
Returns : | Session management ID for this client; NULL if not connected to a session manager.

### gnome_client_get_previous_id ()

    gchar*      gnome_client_get_previous_id    (GnomeClient *client);

Get the previous session management ID (from previous session)

`client` : | Pointer to GNOME session client object.
Returns : | Pointer to the session management ID the client had in the last session, or NULL if it wasn't in a previous session.

### gnome_client_get_config_prefix ()

    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.

`client` : | Pointer to GNOME session client object.
Returns : | Config prefix.

### gnome_client_get_global_config_prefix ()

    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.

`client` : | Pointer to GNOME session client object.
Returns : | The config prefix as a newly allocated string

### gnome_client_set_global_config_prefix ()

    void        gnome_client_set_global_config_prefix
                                                (GnomeClient *client,
                                                 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.

`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);

`client` : | Pointer to GNOME session client object.
Returns : | some flags, that give additional information about this client. Right now, the following flags are supported: - GNOME_CLIENT_IS_CONNECTED: The client is connected to a session manager (It's the same information like using * GNOME_CLIENT_CONNECTED). - GNOME_CLIENT_RESTARTED: The client has been restarted, i. e. it has been running with the same client id before. - GNOME_CLIENT_RESTORED: This flag is only used for the master client. It indicates, that there may be a configuraion file from which the clients state should be restored (using the gnome_client_get_config_prefix call).

### gnome_client_set_restart_style ()

    void        gnome_client_set_restart_style  (GnomeClient *client,
                                                 GnomeRestartStyle style);

GNOME_RESTART_IF_RUNNING causes the client to be restarted in the next session if it was running when the previous session exited. Restart is done via the restart command you set. GNOME_RESTART_ANYWAY means the client will be restarted even if the user exits the client before logging out. GNOME_RESTART_IMMEDIATELY restarts the client immediately anytime it crashes or is exited.

`client` : | Pointer to GNOME session client object.
`style` : | When to restart the client

### 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.

`client` : | Pointer to GNOME session client object.
`argc` : | number of strings in argv
`argv` : | argument vector to <function>execv()</function> 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 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 specified by the user on the original command line.

`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[]);

Provides a command to run when a client is removed from the session. It might delete session-specific config files for example. Executing the discard command on the local host should delete the information saved as part of the session save that was in progress when the discard command was set. For example:

<example> gchar *prefix = gnome_client_get_config_prefix (client); gchar *argv[] = { "rm", "-r", NULL }; argv[2] = gnome_config_get_real_path (prefix); gnome_client_set_discard_command (client, 3, argv); </example>

`client` : | Pointer to GNOME session client object.
`argc` : | Number of strings in argv
`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.

`client` : | Pointer to GNOME session client object.
`argc` : | number of strings in argv
`argv` : |

### 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.

`client` : | Pointer to GNOME session client object.
`argc` : | number of strings in argv
`argv` : |

### 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.

`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.

`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.

`client` : | Pointer to GNOME session client object.
`argc` : | number of strings in the argv vector
`argv` : |

### 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 <function>getpid()</function>. However, Gnome does this automatically; so you don't need this function.

`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.

`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 *user_id);

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

`client` : | Pointer to GNOME session client object.
`user_id` : |

### 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.

`client` : | Pointer to GNOME session client object.

### gnome_client_save_any_dialog ()

    void        gnome_client_save_any_dialog    (GnomeClient *client,
                                                 GnomeDialog *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 interact_style == GNOME_INTERACT_ANY. A "Cancel Logout" button will be added during a shutdown.

`client` : | Pointer to GNOME session client object.
`dialog` : | Pointer to GNOME dialog widget.

### gnome_client_save_error_dialog ()

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

May be called during a "save_youself" handler when an error has occured during the save. The session manager decides when the dialog is shown but it will not be shown when the interact_style == GNOME_INTERACT_NONE. A "Cancel Logout" button will be added during a shutdown.

`client` : | Pointer to GNOME session client object.
`dialog` : | Pointer to GNOME dialog widget.

### gnome_client_request_interaction ()

    void        gnome_client_request_interaction
                                                (GnomeClient *client,
                                                 GnomeDialogType dialog,
                                                 GnomeInteractFunction func,
                                                 gpointer client_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/error]_dialog. 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'.

`client` : | Pointer to GNOME session client object.
`dialog` : |
`func` : |
`client_data` : |

### gnome_client_request_interaction_interp ()

    void        gnome_client_request_interaction_interp
                                                (GnomeClient *client,
                                                 GnomeDialogType dialog,
                                                 GtkCallbackMarshal func,
                                                 gpointer data,
                                                 GtkDestroyNotify destroy);

Used when you need to destroy the callback data after the interaction.

`client` : | Pointer to GNOME session client object.
`dialog` : |
`func` : |
`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're done interacting

`key` : | Key passed to interaction callback
`cancel_shutdown` : | if TRUE then cancel the shutdown

### 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.

`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 ASAP
`global` : | request that all other apps in the session also save

### 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.

`client` : | Pointer to GNOME session client object.

### gnome_client_init ()

    void        gnome_client_init               (void);

<<< Previous Page | Home | Up | Next Page >>>
GnomeCanvasWidget | GnomeColorPicker