XfceSMClient

## XfceSMClient XfceSMClient — Session management client |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libxfce4ui/libxfce4ui.h>

                        XfceSMClient;
    enum                XfceSMClientPriority;
    enum                XfceSMClientRestartStyle;
    enum                XfceSMClientShutdownHint;
    GOptionGroup *      xfce_sm_client_get_option_group     (gint argc,
                                                             gchar **argv);
    XfceSMClient *      xfce_sm_client_get                  (void);
    XfceSMClient *      xfce_sm_client_get_with_argv        (gint argc,
                                                             gchar **argv,
                                                             XfceSMClientRestartStyle restart_style,
                                                             guchar priority);
    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);
    gboolean            xfce_sm_client_connect              (XfceSMClient *sm_client,
                                                             GError **error);
    void                xfce_sm_client_disconnect           (XfceSMClient *sm_client);
    gboolean            xfce_sm_client_is_connected         (XfceSMClient *sm_client);
    gboolean            xfce_sm_client_is_resumed           (XfceSMClient *sm_client);
    void                xfce_sm_client_set_desktop_file     (XfceSMClient *sm_client,
                                                             const gchar *desktop_file);
    void                xfce_sm_client_request_shutdown     (XfceSMClient *sm_client,
                                                             XfceSMClientShutdownHint shutdown_hint);
    const gchar *       xfce_sm_client_get_client_id        (XfceSMClient *sm_client);
    const gchar *       xfce_sm_client_get_state_file       (XfceSMClient *sm_client);
    const gchar *       xfce_sm_client_get_current_directory
                                                            (XfceSMClient *sm_client);
    void                xfce_sm_client_set_current_directory
                                                            (XfceSMClient *sm_client,
                                                             const gchar *current_directory);
    guint8              xfce_sm_client_get_priority         (XfceSMClient *sm_client);
    void                xfce_sm_client_set_priority         (XfceSMClient *sm_client,
                                                             guint8 priority);
    const gchar * const * xfce_sm_client_get_restart_command
                                                            (XfceSMClient *sm_client);
    void                xfce_sm_client_set_restart_command  (XfceSMClient *sm_client,
                                                             gchar **restart_command);
    XfceSMClientRestartStyle xfce_sm_client_get_restart_style
                                                            (XfceSMClient *sm_client);
    void                xfce_sm_client_set_restart_style    (XfceSMClient *sm_client,
                                                             XfceSMClientRestartStyle restart_style);

## Object Hierarchy

      GObject
       +----XfceSMClient

      GEnum
       +----XfceSMClientRestartStyle

      GEnum
       +----XfceSMClientShutdownHint

## Properties

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

## Signals

      "quit"                                           : Run Last
      "quit-cancelled"                                 : Run Last
      "quit-requested"                                 : Run Last
      "save-state"                                     : Run Last
      "save-state-extended"                            : Run Last

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

## Details

### XfceSMClient

    typedef struct _XfceSMClient XfceSMClient;

An opaque struct with only private fields.

### enum XfceSMClientPriority

    typedef enum {
        XFCE_SM_CLIENT_PRIORITY_HIGHEST = 0,
        XFCE_SM_CLIENT_PRIORITY_WM = 15,
        XFCE_SM_CLIENT_PRIORITY_CORE = 25,
        XFCE_SM_CLIENT_PRIORITY_DESKTOP = 35,
        XFCE_SM_CLIENT_PRIORITY_DEFAULT = 50,
        XFCE_SM_CLIENT_PRIORITY_LOWEST = 255,
    } XfceSMClientPriority;

Some sample priority values for use with `xfce_sm_client_set_priority()`.

`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

    typedef enum {
        XFCE_SM_CLIENT_RESTART_NORMAL = 0,
        XFCE_SM_CLIENT_RESTART_IMMEDIATELY,
    } XfceSMClientRestartStyle;

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

`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

    typedef enum {
        XFCE_SM_CLIENT_SHUTDOWN_HINT_ASK = 0,
        XFCE_SM_CLIENT_SHUTDOWN_HINT_LOGOUT,
        XFCE_SM_CLIENT_SHUTDOWN_HINT_HALT,
        XFCE_SM_CLIENT_SHUTDOWN_HINT_REBOOT,
    } XfceSMClientShutdownHint;

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

`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_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:

    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.

`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 are not using Gtk or Glib's command-line option parser, take a look at `xfce_sm_client_new_with_argv()` and `xfce_sm_client_new_full()`.

If you have already created an XfceSMClient instance using this function or one of the xfce_sm_client_new_*() functions, this will return the same instance.

Returns : | A new or existing XfceSMClient

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

`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

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

`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

### xfce_sm_client_connect ()

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

Attempts to connect to the session manager.

`sm_client` : | An XfceSMClient
`error` : | A GError location.
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.

### Note

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.

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

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

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

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

### Note

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

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

### Note

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

`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 program identifier set (see `xfce_sm_client_set_program()`) and a valid client ID (see `xfce_sm_client_get_client_id()`).

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

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

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

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

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

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

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

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

`sm_client` : | An XfceSMClient
`restart_style` : | An XfceSMClientRestartStyle value

## Property Details

### The `"argc"` property

      "argc"                     gint                  : Write / Construct Only

Argument count passed to program.

Default value: 0

### The `"argv"` property

      "argv"                     GStrv                 : Write / Construct Only

Argument vector passed to program.

### The `"client-id"` property

      "client-id"                gchar*                : Read / Write / Construct Only

A string uniquely identifying the current instance of this client.

Default value: NULL

### The `"current-directory"` property

      "current-directory"        gchar*                : Read / Write

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

Default value: NULL

### The `"desktop-file"` property

      "desktop-file"             gchar*                : Read / Write

The application's .desktop file.

Default value: NULL

### The `"priority"` property

      "priority"                 guchar                : Read / Write / Construct

Determines the ordering in which this client is restarted.

Default value: 50

### The `"restart-command"` property

      "restart-command"          GStrv                 : Read / Write

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

### The `"restart-style"` property

      "restart-style"            XfceSMClientRestartStyle  : Read / Write / Construct

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

Default value: XFCE_SM_CLIENT_RESTART_NORMAL

### The `"resumed"` property

      "resumed"                  gboolean              : Read

Whether or not the client was resumed with previous state.

Default value: FALSE

## Signal Details

### The `"quit"` signal

    void                user_function                      (XfceSMClient *sm_client,
                                                            gpointer      user_data)      : Run Last

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.

`sm_client` : | An XfceSMClient
`user_data` : | user data set when the signal handler was connected.

### The `"quit-cancelled"` signal

    void                user_function                      (XfceSMClient *sm_client,
                                                            gpointer      user_data)      : Run Last

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

`sm_client` : | An XfceSMClient
`user_data` : | user data set when the signal handler was connected.

### The `"quit-requested"` signal

    gboolean            user_function                      (XfceSMClient *sm_client,
                                                            gpointer      user_data)      : Run Last

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

`sm_client` : | An XfceSMClient
`user_data` : | user data set when the signal handler was connected.

### The `"save-state"` signal

    void                user_function                      (XfceSMClient *sm_client,
                                                            gpointer      user_data)      : Run Last

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.

`sm_client` : | An XfceSMClient
`user_data` : | user data set when the signal handler was connected.

### The `"save-state-extended"` signal

    void                user_function                      (XfceSMClient *sm_client,
                                                            gpointer      user_data)      : Run Last

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.

`sm_client` : | An XfceSMClient
`user_data` : | user data set when the signal handler was connected.