Gnome User Interface Library Reference Manual
PrevNext

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

Signal Prototypes


'save-yourself'
            gboolean    user_function      (GnomeClient *client,
                                            gint arg1,
                                            GtkEnum arg2,
                                            gboolean arg3,
                                            GtkEnum arg4,
                                            gboolean arg5,
                                            gpointer user_data);
'die'       void        user_function      (GnomeClient *client,
                                            gpointer user_data);
'save-complete'
            void        user_function      (GnomeClient *client,
                                            gpointer user_data);
'shutdown-cancelled'
            void        user_function      (GnomeClient *client,
                                            gpointer user_data);
'connect'   void        user_function      (GnomeClient *client,
                                            gboolean arg1,
                                            gpointer user_data);
'disconnect'
            void        user_function      (GnomeClient *client,
                                            gpointer user_data);

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.

Details

GnomeClient

struct GnomeClient;

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)

obj : 

GnomeInteractStyle

typedef enum
{
  GNOME_INTERACT_NONE,
  GNOME_INTERACT_ERRORS,
  GNOME_INTERACT_ANY
} GnomeInteractStyle;

GnomeDialogType

typedef enum
{
  GNOME_DIALOG_ERROR,
  GNOME_DIALOG_NORMAL
} GnomeDialogType;

GnomeSaveStyle

typedef enum
{
  GNOME_SAVE_GLOBAL,
  GNOME_SAVE_LOCAL,
  GNOME_SAVE_BOTH
} GnomeSaveStyle;

GnomeRestartStyle

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

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

client : key : dialog_type : data : 

gnome_client_disable_master_connection()

void        gnome_client_disable_master_connection
                                            (void);

gnome_master_client()

GnomeClient* gnome_master_client            (void);

Returns : Pointer to

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.

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.

Returns : Pointer to a newly allocated GNOME session management client object.

gnome_client_connect()

void        gnome_client_connect            (GnomeClient *client);

client : Pointer to GNOME session client object.

gnome_client_disconnect()

void        gnome_client_disconnect         (GnomeClient *client);

client : Pointer to GNOME session client object.

gnome_client_set_id()

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

client : Pointer to GNOME session client object.client_id : 

gnome_client_get_id()

gchar*      gnome_client_get_id             (GnomeClient *client);

client : Pointer to GNOME session client object.Returns : Pointer to

gnome_client_get_previous_id()

gchar*      gnome_client_get_previous_id    (GnomeClient *client);

client : Pointer to GNOME session client object.Returns : Pointer to

gnome_client_get_config_prefix()

gchar*      gnome_client_get_config_prefix  (GnomeClient *client);

client : Pointer to GNOME session client object.Returns : Pointer to

gnome_client_get_global_config_prefix()

gchar*      gnome_client_get_global_config_prefix
                                            (GnomeClient *client);

client : Pointer to GNOME session client object.Returns : Pointer to

gnome_client_set_global_config_prefix()

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

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

client : Pointer to GNOME session client object.style : 

gnome_client_set_restart_command()

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

client : Pointer to GNOME session client object.argc : argv : 

gnome_client_add_static_arg()

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

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

gnome_client_set_discard_command()

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

client : Pointer to GNOME session client object.argc : argv : 

gnome_client_set_resign_command()

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

client : Pointer to GNOME session client object.argc : argv : 

gnome_client_set_shutdown_command()

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

client : Pointer to GNOME session client object.argc : argv : 

gnome_client_set_current_directory()

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

client : Pointer to GNOME session client object.dir : 

gnome_client_set_environment()

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

client : Pointer to GNOME session client object.name : value : 

gnome_client_set_clone_command()

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

client : Pointer to GNOME session client object.argc : argv : 

gnome_client_set_process_id()

void        gnome_client_set_process_id     (GnomeClient *client,
                                             pid_t pid);

client : Pointer to GNOME session client object.pid : 

gnome_client_set_program()

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

client : Pointer to GNOME session client object.program : 

gnome_client_set_user_id()

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

client : Pointer to GNOME session client object.user_id : 

gnome_client_request_phase_2()

void        gnome_client_request_phase_2    (GnomeClient *client);

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

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

client : Pointer to GNOME session client object.dialog : func : data : destroy : 

gnome_interaction_key_return()

void        gnome_interaction_key_return    (gint key,
                                             gboolean cancel_shutdown);

key : cancel_shutdown : 

gnome_client_request_save()

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

client : Pointer to GNOME session client object.save_style : shutdown : interact_style : fast : global : 

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

Signals

The 'save-yourself' signal

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

This signal is probably the most important one, because it causes the clients to save the programs state. Clients should connect to this signal and save their state.

client :the object which received the signal.arg1 : arg2 : arg3 : arg4 : arg5 : user_data :user data set when the signal handler was connected.Returns : 

The 'die' signal

void        user_function                  (GnomeClient *client,
                                            gpointer user_data);

client :the object which received the signal. user_data :user data set when the signal handler was connected.

The 'save-complete' signal

void        user_function                  (GnomeClient *client,
                                            gpointer user_data);

client :the object which received the signal. user_data :user data set when the signal handler was connected.

The 'shutdown-cancelled' signal

void        user_function                  (GnomeClient *client,
                                            gpointer user_data);

client :the object which received the signal. user_data :user data set when the signal handler was connected.

The 'connect' signal

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

client :the object which received the signal.arg1 : user_data :user data set when the signal handler was connected.

The 'disconnect' signal

void        user_function                  (GnomeClient *client,
                                            gpointer user_data);

client :the object which received the signal. user_data :user data set when the signal handler was connected.

PrevHomeNext
GnomeCanvasWidgetUpGnomeColorPicker