XfceSMClient

XfceSMClient — Session management client

Stability Level

Stable, unless otherwise indicated

Functions

Properties

int argc Write / Construct Only
GStrv argv Write / Construct Only
char * client-id Read / Write / Construct Only
char * current-directory Read / Write
char * desktop-file Read / Write
guchar priority Read / Write / Construct
GStrv restart-command Read / Write
XfceSMClientRestartStyle restart-style Read / Write / Construct
gboolean resumed Read

Signals

void quit Run Last
void quit-cancelled Run Last
gboolean quit-requested Run Last
void save-state Run Last
void save-state-extended Run Last

Types and Values

Object Hierarchy

    GEnum
    ├── XfceSMClientRestartStyle
    ├── XfceSMClientShutdownHint
    ╰── XfceSmCLientErrorEnum
    GObject
    ╰── XfceSMClient

Includes

#include <libxfce4ui/libxfce4ui.h>

Description

XfceSMClient is a session management client that speaks the X Session Management Protocol (XSMP). It's designed to be easy to use and hide some of the more esoteric feaures of XSMP from the API user.

Functions

xfce_sm_client_get_option_group ()

GOptionGroup *
xfce_sm_client_get_option_group (gint argc,
                                 gchar **argv);

Constructs a GOptionGroup suitable for use with Glib's command-line option parser.

This function is a bit sneaky in that it will make a copy of the program's argc and argv before GTK+ etc. has a chance to mess around with it, so XfceSMClient can later construct an accurate restart command. Instead of calling gtk_init() or gtk_init_with_args(), instead you'd do something like:

1
2
3
4
GOptionContext *context = g_option_context_new("");
g_option_context_add_group(context, gtk_get_option_group(TRUE));
g_option_context_add_group(context, xfce_sm_client_get_option_group(argc, argv);
g_option_context_parse(context, &argc, &argv, NULL);

Error checking is omitted here for brevity, and of course you could add your app's own options with g_option_context_add_main_entries() or similar.

Parameters

argc

The application's argument count

 

argv

The application's argument vector

 

Returns

A new GOptionGroup


xfce_sm_client_get ()

XfceSMClient *
xfce_sm_client_get (void);

Gets the application's SM client instance. This is best used with xfce_sm_client_get_option_group() above (and using the returned GOptionGroup with g_option_context_parse()), as the command line parsing will figure out many of the SM client's required property values for you.

If you have already created an XfceSMClient instance using this function, this will return the same instance, i.e. you should *only* unref the first instance.

[constructor]

Returns

A new XfceSMClient instance -transfer full- on the first call only, other calls to this function are transfer none


xfce_sm_client_get_with_argv ()

XfceSMClient *
xfce_sm_client_get_with_argv (gint argc,
                              gchar **argv,
                              XfceSMClientRestartStyle restart_style,
                              guchar priority);

Creates a new XfceSMClient instance. It attempts to set all required properties using the app's command line. Note that this function does not actually connect to the session manager, so other actions can be taken (such as setting custom properties or connecting signals) before calling xfce_sm_client_connect().

If you are using Gtk or Glib's command-line option parser, it is recommended that you use xfce_sm_client_get_option_group() and xfce_sm_client_get() instead.

[constructor]

Parameters

argc

The number of arguments passed to main()

 

argv

The argument vector passed to main()

 

restart_style

An XfceSMClientRestartStyle

 

priority

A restart priority

 

Returns

A new XfceSMClient instance.

[transfer full]


xfce_sm_client_get_full ()

XfceSMClient *
xfce_sm_client_get_full (XfceSMClientRestartStyle restart_style,
                         guchar priority,
                         const gchar *resumed_client_id,
                         const gchar *current_directory,
                         const gchar **restart_command,
                         const gchar *desktop_file);

Creates a new SM client instance, allowing the application fine-grained control over the initial properties set. Note that this function does not actually connect to the session manager, so other actions can be taken (such as setting custom properties or connecting signals) before calling xfce_sm_client_connect().

It is recommended to use xfce_sm_client_get_with_argv(), or, if you are using Gtk or Glib's command-line option parser, xfce_sm_client_get_option_group() and xfce_sm_client_get() instead.

[constructor]

Parameters

restart_style

An XfceSMClientRestartStyle

 

priority

A restart priority

 

resumed_client_id

The client id used in the previous session

 

current_directory

The application's working directory

 

restart_command

A command that can resume the application's saved state

 

desktop_file

The application's .desktop file

 

Returns

A new XfceSMClient instance.

[transfer full]


xfce_sm_client_connect ()

gboolean
xfce_sm_client_connect (XfceSMClient *sm_client,
                        GError **error);

Attempts to connect to the session manager.

Parameters

sm_client

An XfceSMClient

 

error

A GError location.

[out][nullable][transfer full]

Returns

TRUE on success, FALSE otherwise. If an error occurs, error will be set.


xfce_sm_client_disconnect ()

void
xfce_sm_client_disconnect (XfceSMClient *sm_client);

Disconnects the application from the session manager.

This may not remove the application from the saved session (if any) if the user later does not choose to save the session when logging out.

Parameters

sm_client

An XfceSMClient

 

xfce_sm_client_is_connected ()

gboolean
xfce_sm_client_is_connected (XfceSMClient *sm_client);

Determines whether or not the application has connected to the session manager.

Parameters

sm_client

An XfceSMClient

 

Returns

TRUE if connected to the session manager, FALSE otherwise


xfce_sm_client_is_resumed ()

gboolean
xfce_sm_client_is_resumed (XfceSMClient *sm_client);

Determines whether the application was resumed from a previous session, or if the application has been started fresh with no state information associated with it.

Parameters

sm_client

An XfceSMClient

 

Returns

TRUE if resumed from a previous session, FALSE otherwise


xfce_sm_client_set_desktop_file ()

void
xfce_sm_client_set_desktop_file (XfceSMClient *sm_client,
                                 const gchar *desktop_file);

Sets the application's .desktop file. In addition to informing the session manager of the .desktop file so it can present localized names and an icon in session listings and the splash screen, this also calls g_set_application_name() and gtk_window_set_default_icon_name() (or gtk_window_set_default_icon_from_file()) if the Name and Icon keys are present, respectively.

If a relative path to the file is provided, this function will search the standard application directories as specified by the

XDG Desktop Menu Specification.

Parameters

sm_client

An XfceSMClient

 

desktop_file

The path to the application's .desktop file

 

xfce_sm_client_request_shutdown ()

void
xfce_sm_client_request_shutdown (XfceSMClient *sm_client,
                                 XfceSMClientShutdownHint shutdown_hint);

Sends a request to the session manager to end the session. Depending on hint , the session manager may prompt for a certain action (log out, halt, reboot, etc.) or may take the requested action without user intervention.

The session manager may or may not support all requested actions, and is also free to ignore the requested action.

Parameters

sm_client

An XfceSMClient

 

shutdown_hint

The type of shutdown requested

 

xfce_sm_client_get_client_id ()

const gchar *
xfce_sm_client_get_client_id (XfceSMClient *sm_client);

Retrieves the session client's unique ID. This ID can be used to construct a filename used to restore the application's state. Note that this value is only guaranteed to be valid if connected to the session manager.

Instead of constructing a state filename, it is recommended to use xfce_sm_client_get_state_file().

Parameters

sm_client

An XfceSMClient

 

Returns

an opaque object-owned string


xfce_sm_client_get_state_file ()

const gchar *
xfce_sm_client_get_state_file (XfceSMClient *sm_client);

Constructs a filename that can be used to restore or save state information.

When saving state, ote that this file may already exist (and may have been used for saving previous state for the application), so the application should first remove or empty the file if it requires a fresh state file.

On the next application start, this function can be used to check to see if there is any previous saved state, and, if so, the state can be restored from the file.

This function will use a standard location and naming scheme and handle state cleanup (setting of the discard command) for you.

Before calling this function, the application must have a valid client ID (see xfce_sm_client_get_client_id()).

Parameters

sm_client

An XfceSMClient

 

Returns

a file name string, owned by the object or NULL if the session client is disabled.


xfce_sm_client_get_current_directory ()

const gchar *
xfce_sm_client_get_current_directory (XfceSMClient *sm_client);

Retrieves the session client's working directory. See xfce_sm_client_set_current_directory() for more information.

Parameters

sm_client

An XfceSMClient

 

Returns

an object-owned string


xfce_sm_client_set_current_directory ()

void
xfce_sm_client_set_current_directory (XfceSMClient *sm_client,
                                      const gchar *current_directory);

Sets the startup working directory of sm_client to current_directory . If unset, defaults to the user's home directory.

Parameters

sm_client

An XfceSMClient

 

current_directory

A valid path name

 

xfce_sm_client_get_priority ()

guint8
xfce_sm_client_get_priority (XfceSMClient *sm_client);

Retrieves the session client's restart priority. See xfce_sm_client_set_priority() for more information.

Parameters

sm_client

An XfceSMClient

 

Returns

a value from G_MININT8 to G_MAXINT8


xfce_sm_client_set_priority ()

void
xfce_sm_client_set_priority (XfceSMClient *sm_client,
                             guint8 priority);

Sets the startup priority for sm_client to priority . Note that the default priority for applications is 50; lower values should be reserved for components of the desktop environment.

Parameters

sm_client

An XfceSMClient

 

priority

A 8-bit signed priority value

 

xfce_sm_client_get_restart_command ()

const gchar * const *
xfce_sm_client_get_restart_command (XfceSMClient *sm_client);

Retrieves the session client's restart command. See xfce_sm_client_set_restart_command() for more information.

Parameters

sm_client

An XfceSMClient

 

Returns

an object-owned string vector


xfce_sm_client_set_restart_command ()

void
xfce_sm_client_set_restart_command (XfceSMClient *sm_client,
                                    gchar **restart_command);

Sets the application's "restart" command, which is used to restart the application and restore any saved state from the previous run.

If unset, defaults to the command used to start this instance of the application, with session management related arguments added (if not already present).

Parameters

sm_client

An XfceSMClient

 

restart_command

An argument vector

 

xfce_sm_client_get_restart_style ()

XfceSMClientRestartStyle
xfce_sm_client_get_restart_style (XfceSMClient *sm_client);

Retrieves the session client's restart style. See xfce_sm_client_set_restart_style() for more information.

Parameters

sm_client

An XfceSMClient

 

Returns

a value from the XfceSMClientRestartStyle enum


xfce_sm_client_set_restart_style ()

void
xfce_sm_client_set_restart_style (XfceSMClient *sm_client,
                                  XfceSMClientRestartStyle restart_style);

Sets the restart style hint to restart_style .

Parameters

sm_client

An XfceSMClient

 

restart_style

An XfceSMClientRestartStyle value

 

Types and Values

XfceSMClient

typedef struct _XfceSMClient XfceSMClient;

An opaque struct with only private fields.


enum XfceSMClientPriority

Some sample priority values for use with xfce_sm_client_set_priority().

Members

XFCE_SM_CLIENT_PRIORITY_HIGHEST

A high priority value. You probably don't want to use this.

 

XFCE_SM_CLIENT_PRIORITY_WM

A priority value for use by the window manager.

 

XFCE_SM_CLIENT_PRIORITY_CORE

A priority value for use by applications that place windows on the screen and possibly set window manager struts.

 

XFCE_SM_CLIENT_PRIORITY_DESKTOP

A priority value for use by applications that draw on the desktop.

 

XFCE_SM_CLIENT_PRIORITY_DEFAULT

A priority value for regular applications.

 

XFCE_SM_CLIENT_PRIORITY_LOWEST

The lowest possible priority value.

 

enum XfceSMClientRestartStyle

An enumeration describing how the session manager should restart the application.

Members

XFCE_SM_CLIENT_RESTART_NORMAL

Only restart the application if it is still running when the session is next saved.

 

XFCE_SM_CLIENT_RESTART_IMMEDIATELY

Immediately restart the application if it ever quits.

 

enum XfceSMClientShutdownHint

Hints to the session manager what kind of shutdown the session manager should perform.

Members

XFCE_SM_CLIENT_SHUTDOWN_HINT_ASK

Prompt the user for a choice,

 

XFCE_SM_CLIENT_SHUTDOWN_HINT_LOGOUT

End the current session,

 

XFCE_SM_CLIENT_SHUTDOWN_HINT_HALT

Shut down the computer.

 

XFCE_SM_CLIENT_SHUTDOWN_HINT_REBOOT

Restart the computer.

 

XFCE_SM_CLIENT_ERROR

#define XFCE_SM_CLIENT_ERROR xfce_sm_client_error_quark()

Error domain for XfceSmCLient. Errors in this domain will be from the XfceSmCLientErrorEnum enumeration. See GError for more information on error domains.


enum XfceSmCLientErrorEnum

Error codes returned by XfceSmCLient functions.

Members

XFCE_SM_CLIENT_ERROR_FAILED

Failed to connect to the session manager.

 

XFCE_SM_CLIENT_ERROR_INVALID_CLIENT

Session does not have a valid client id.

 

Property Details

The “argc” property

  “argc”                     int

Argument count passed to program.

Owner: XfceSMClient

Flags: Write / Construct Only

Default value: 0


The “argv” property

  “argv”                     GStrv

Argument vector passed to program.

Owner: XfceSMClient

Flags: Write / Construct Only


The “client-id” property

  “client-id”                char *

A string uniquely identifying the current instance of this client.

Owner: XfceSMClient

Flags: Read / Write / Construct Only

Default value: NULL


The “current-directory” property

  “current-directory”        char *

The directory that should be used as the working directory the next time this client is restarted.

Owner: XfceSMClient

Flags: Read / Write

Default value: NULL


The “desktop-file” property

  “desktop-file”             char *

The application's .desktop file.

Owner: XfceSMClient

Flags: Read / Write

Default value: NULL


The “priority” property

  “priority”                 guchar

Determines the ordering in which this client is restarted.

Owner: XfceSMClient

Flags: Read / Write / Construct

Default value: 50


The “restart-command” property

  “restart-command”          GStrv

A command used to restart this application, preserving the current state.

Owner: XfceSMClient

Flags: Read / Write


The “restart-style” property

  “restart-style”            XfceSMClientRestartStyle

Specifies how the client should be restarted by the session manager.

Owner: XfceSMClient

Flags: Read / Write / Construct

Default value: XFCE_SM_CLIENT_RESTART_NORMAL


The “resumed” property

  “resumed”                  gboolean

Whether or not the client was resumed with previous state.

Owner: XfceSMClient

Flags: Read

Default value: FALSE

Signal Details

The “quit” signal

void
user_function (XfceSMClient *sm_client,
               gpointer      user_data)

Emitted when the application is required to quit. This is not optional: if the client does not quit a short time after receiving this signal, it will likely be terminated in some other way. While not required, the application will usually receive quit-requested before receiving quit. If the application does not connect to this signal, XfceSMClient will call exit(3) with an exit code of zero on behalf of the application.

Parameters

sm_client

An XfceSMClient

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “quit-cancelled” signal

void
user_function (XfceSMClient *sm_client,
               gpointer      user_data)

Informs the application that it will not need to quit. In most cases, quit-cancelled will be emitted a short time after quit-requested.

Parameters

sm_client

An XfceSMClient

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “quit-requested” signal

gboolean
user_function (XfceSMClient *sm_client,
               gpointer      user_data)

Signals the client that the session manager will soon want the application to quit, perhaps as a part of ending the session (but this should not be assumed). The application can take this opportunity to prompt the user to save any unsaved work to disk.

This signal also expects a return value from the handler. If the application wishes to cancel the quit request (perhaps because the user selected "Cancel" in prompts to save unsaved work), it should return TRUE from the handler. If the application is satisfied with possibly needing to quit soon, the handler should return FALSE.

Parameters

sm_client

An XfceSMClient

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “save-state” signal

void
user_function (XfceSMClient *sm_client,
               gpointer      user_data)

Signals the client that it should save a copy of its current state such that it could be restarted later in exactly the same state as it is at the time of signal emission.

If the state is simple enough to be encoded in the application's command line, xfce_sm_client_set_restart_command() can be used to set that command line. For more complex state data, xfce_sm_client_get_state_file() should be used.

The application should attempt to save its state as quickly as possible, and MUST NOT interact with the user as a part of saving state.

Parameters

sm_client

An XfceSMClient

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “save-state-extended” signal

void
user_function (XfceSMClient *sm_client,
               gpointer      user_data)

Allows the application to save extra state information after all other applications in the session have had a chance to save their state. This is mainly used by the window manager to save window positions. Most applications should not need to connect to this signal.

Parameters

sm_client

An XfceSMClient

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last