Next: , Previous: GnomeAuthentication, Up: Top


3 GnomeClient

Interactions with the session manager.

3.1 Overview

3.2 Usage

— Class: <gnome-client>

Derives from <gtk-object>.

This class defines no direct slots.

— Signal on <gnome-client>: save-yourself (arg0 <gint>) (arg1 <gnome-save-style>) (arg2 <gboolean>) (arg3 <gnome-interact-style>) (arg4 <gboolean>) ⇒ <gboolean>

Called when either a "SaveYourself" or a "SaveYourselfPhase2" call is made by the session manager.

— Signal on <gnome-client>: die

Called when the session manager wants the client to shut down.

— Signal on <gnome-client>: save-complete

Called when the session manager has finished checkpointing all of the clients. Clients are then free to change their state.

— Signal on <gnome-client>: shutdown-cancelled

Called if the session manager had sent a "SaveYourself" to all clients in preparation for shutting down and the shutdown was then cancelled. A client can then continue running and change its state.

— Signal on <gnome-client>: connect (arg0 <gboolean>)

Called once the client has been connected to the signal manager.

— Signal on <gnome-client>: disconnect

Called when the client is disconnected from the session manager.

— Function: gnome-master-client ⇒  (ret <gnome-client>)

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.

ret
Pointer to the master client
— Function: gnome-client-get-config-prefix (self <gnome-client>) ⇒  (ret mchars)
— Method: get-config-prefix

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.
ret
Config prefix. The returned string belongs to libgnomeui library and should NOT be freed by the caller.
— Function: gnome-client-get-flags (self <gnome-client>) ⇒  (ret <gnome-client-flags>)
— Method: get-flags

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

client
Pointer to GNOME session client object.
ret
Various <gnome-client-flag> flags which have been or'd together.
— Function: gnome-client-set-restart-style (self <gnome-client>) (style <gnome-restart-style>)
— Method: set-restart-style

Tells the session manager how the client should be restarted in future session. The options are given by the <gnome-restart-style> enum.

client
Pointer to GNOME session client object.
style
When to restart the client.
— Function: gnome-client-set-priority (self <gnome-client>) (priority unsigned-int)
— Method: set-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.

client
Pointer to GNOME session client object.
priority
Position of client in session start up ordering.
— Function: gnome-client-set-current-directory (self <gnome-client>) (dir mchars)
— Method: set-current-directory

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

client
Pointer to GNOME session client object.
dir
Directory path.
— Function: gnome-client-set-environment (self <gnome-client>) (name mchars) (value mchars)
— Method: set-environment

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
— Function: gnome-client-set-process-id (self <gnome-client>) (pid int)
— Method: set-process-id

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

client
Pointer to GNOME session client object.
pid
PID to set as the client's PID.
— Function: gnome-client-set-program (self <gnome-client>) (program mchars)
— Method: set-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.
— Function: gnome-client-set-user-id (self <gnome-client>) (id mchars)
— Method: set-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.
id
Username.
— Function: gnome-client-save-any-dialog (self <gnome-client>) (dialog <gtk-dialog>)
— Method: save-any-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.

client
Pointer to <gnome-client> object.
dialog
Pointer to GNOME dialog widget (a <gtk-dialog> widget).
— Function: gnome-client-save-error-dialog (self <gnome-client>) (dialog <gtk-dialog>)
— Method: save-error-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.

client
Pointer to <gnome-client> object.
dialog
Pointer to GNOME dialog widget (a <gtk-dialog> widget).
— Function: gnome-client-request-phase-2 (self <gnome-client>)
— Method: request-phase-2

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
A <gnome-client> object.
— Function: gnome-client-request-save (self <gnome-client>) (save_style <gnome-save-style>) (shutdown bool) (interact_style <gnome-interact-style>) (fast bool) (global bool)
— Method: request-save

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 ‘#t’ will initiate a logout. The interact_style specifies which kinds of interaction will be available. Setting fast to ‘#t’ will limit the save to setting the session manager properties plus any essential data. Setting the value of global to ‘#t’ 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 as soon as possible.
global
Request that all other apps in the session also save their state.
— Function: gnome-client-flush (self <gnome-client>)
— Method: flush

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
A <gnome-client> instance.
— Function: gnome-client-new ⇒  (ret <gnome-client>)

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.

ret
Pointer to a newly allocated GNOME session management client object.
— Function: gnome-client-new-without-connection ⇒  (ret <gnome-client>)

Allocates memory for a new GNOME session management client object. You probably want to use gnome-master-client instead.

ret
Pointer to a newly allocated GNOME session management client object.
— Function: gnome-client-connect (self <gnome-client>)
— Method: connect

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

client
A <gnome-client> instance.
— Function: gnome-client-disconnect (self <gnome-client>)
— Method: disconnect

Disconnect the client from the session manager.

client
A <gnome-client> instance.
— Function: gnome-client-set-id (self <gnome-client>) (id mchars)
— Method: set-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.

client
A <gnome-client> instance.
id
Session management ID.
— Function: gnome-client-get-id (self <gnome-client>) ⇒  (ret mchars)
— Method: get-id

Returns session management ID

client
A <gnome-client> instance.
ret
Session management ID for this client; ‘#f’ if not connected to a session manager.
— Function: gnome-client-get-previous-id (self <gnome-client>) ⇒  (ret mchars)
— Method: get-previous-id

Get the session management ID from the previous session.

client
A <gnome-client> instance.
ret
Pointer to the session management ID the client had in the last session, or ‘#f’ if it was not in a previous session.
— Function: gnome-client-get-desktop-id (self <gnome-client>) ⇒  (ret mchars)
— Method: get-desktop-id

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 ‘#f’ for apps not running under a recent version of gnome-session; apps should handle that case.

client
A <gnome-client> instance.
ret
Session ID of GNOME desktop instance, or ‘#f’ if none.