org.gnome.SessionManager
Prev | Part II. Internal D-Bus API | Next

## Name

org.gnome.SessionManager — The Manager

## Methods

    Setenv                   (IN  s  variable,
                              IN  s  value);
    GetLocale                (IN  i  category,
                              OUT s  value);
    InitializationError      (IN  s  message,
                              IN  b  fatal);
    Initialized              ();
    RegisterClient           (IN  s  app_id,
                              IN  s  ignored,
                              OUT o  client_id);
    UnregisterClient         (IN  o  client_id);
    RegisterRestore          (IN  s  app_id,
                              IN  s  dbus_name,
                              OUT u  reason,
                              OUT s  instance_id,
                              OUT as cleanup_ids);
    DeletedInstanceIds       (IN  s  app_id,
                              IN  as ids);
    UnregisterRestore        (IN  s  app_id,
                              IN  s  instance_id);
    Inhibit                  (IN  s  app_id,
                              IN  u  ignored,
                              IN  s  reason,
                              IN  u  flags,
                              OUT u  inhibit_cookie);
    Uninhibit                (IN  u  inhibit_cookie);
    IsInhibited              (IN  u  flags,
                              OUT b  is_inhibited);
    GetInhibitors            (OUT ao inhibitors);
    Shutdown                 ();
    Reboot                   ();
    Suspend                  ();
    CanShutdown              (OUT u  availability);
    CanReboot                (OUT u  availability);
    CanSuspend               (OUT u  availability);
    SetRebootToFirmwareSetup (IN  b  enable);
    CanRebootToFirmwareSetup (OUT b  is_available);
    Logout                   (IN  u  mode);
    IsSessionRunning         (OUT b  running);

## Signals

    ClientAdded      (o id);
    ClientRemoved    (o id);
    InhibitorAdded   (o id);
    InhibitorRemoved (o id);
    SessionRunning   ();
    SessionOver      ();

## Properties

    SessionName       readable   s
    Renderer          readable   s
    SessionIsActive   readable   b
    InhibitedActions  readable   u
    RestoreSupported  readable   b

## Description

## Method Details

### The Setenv() method

    Setenv (IN  s variable,
            IN  s value);

Adds the variable name to the application launch environment with the specified value. May only be used during the Session Manager initialization phase.

`IN s `variable``:

  The variable name

`IN s `value``:

  The variable value

### The GetLocale() method

    GetLocale (IN  i category,
               OUT s value);

Reads the current state of the specific locale category.

`IN i `category``:

  The locale category

`OUT s `value``:

  The value

### The InitializationError() method

    InitializationError (IN  s message,
                         IN  b fatal);

May be used by applications launched during the Session Manager initialization phase to indicate there was a problem.

`IN s `message``:

  The error message

`IN b `fatal``:

  Whether the error should be treated as fatal

### The Initialized() method

    Initialized ();

Run from systemd to signal that gnome-session-initialized.target has been reached.

### The RegisterClient() method

    RegisterClient (IN  s app_id,
                    IN  s ignored,
                    OUT o client_id);

Register the caller as a Session Management client.

`IN s `app_id``:

  The application identifier

`IN s `ignored``:

  An ignored parameter, which exists only to make this API backwards-compatible with older versions of GNOME

`OUT o `client_id``:

  The object path of the newly registered client

### The UnregisterClient() method

    UnregisterClient (IN  o client_id);

Unregister the specified client from Session Management.

`IN o `client_id``:

  The object path of the client

### The RegisterRestore() method

    RegisterRestore (IN  s  app_id,
                     IN  s  dbus_name,
                     OUT u  reason,
                     OUT s  instance_id,
                     OUT as cleanup_ids);

Register the specified app for session save/restore functionality. Apps that register here will be relaunched on next login, and can restore their saved state.

The restore `reason` communicates to an app how much state it should restore. See the following table:

- 0: The app shouldn't restore any state

- 1: This is a normal app launch. The app should restore as much state as is reasonable. For instance: an app like GNOME Calculator may restore the last-used mode (Basic/Advanced/Programmer/...) but won't restore the history.

- 2: This is an app restore after a crash. The app should restore as much state as is possible, but should be careful about causing the crash again. For instance, an app like GNOME Web might immediately load all of its tabs after a normal restore, but only show the "This page may have caused Web to crash" page in each tab after a crash restore. This is also returned if the entire session crashed

- 3: This is a normal app restore. The app was shut down due to logout or some other reason, and the session was cleanly ended. The app should restore as much state as is possible.

The `instance_id` incorporates a string that identifies this session. This means that the app can safely assume that there will never be an instance ID collision with other session managers from other desktop environments, or even other sessions managed by gnome-session.

The instance IDs returned in `cleanup_ids` will never be reused, and the app should delete any data associated with these IDs from disk. When complete, the app should notify the session manager via #DeletedInstanceIds()

This is a private interface between gnome-session and xdg-desktop-portal. Apps should talk to the portal directly for this functionality.

`IN s `app_id``:

  The application identifier

`IN s `dbus_name``:

  The app's dbus unique name, for crash monitoring

`OUT u `reason``:

  The app's restore reason, see below

`OUT s `instance_id``:

  A stable ID for this instance of this app

`OUT as `cleanup_ids``:

  A list of instance IDs the session manager wishes to discard

### The DeletedInstanceIds() method

    DeletedInstanceIds (IN  s  app_id,
                        IN  as ids);

Used to notify the session manager that the app has successfully deleted the instance IDs, and that the manager is now free to forget them for good.

This is a private interface between gnome-session and xdg-desktop-portal. Apps should talk to the portal directly for this functionality.

`IN s `app_id``:

  The application identifier

`IN as `ids``:

  List of instance IDs the application deleted

### The UnregisterRestore() method

    UnregisterRestore (IN  s app_id,
                       IN  s instance_id);

Un-registers the app from the session save/restore functionality. This should be called whenever the app exits cleanly.

This is a private interface between gnome-session and xdg-desktop-portal. Apps should talk to the portal directly for this functionality.

`IN s `app_id``:

  The application identifier

`IN s `instance_id``:

  The application's instance_id

### The Inhibit() method

    Inhibit (IN  s app_id,
             IN  u ignored,
             IN  s reason,
             IN  u flags,
             OUT u inhibit_cookie);

Applications should invoke this method when they begin an operation that should not be interrupted, such as creating a CD or DVD. The types of actions that may be blocked are specified by the flags parameter. When the application completes the operation it should call #Uninhibit() or disconnect from the session bus.

Applications should not expect that they will always be able to block the action. In most cases, users will be given the option to force the action to take place. If `app_id` is not specified, the user might not be informed of this inhibitor when prompted to force the action.

The `flags` parameter must include at least one of the following flags, bitwise or'ed together:

- 1: Inhibit logging out

- 2: Inhibit user switching

- 4: Inhibit suspending the session or computer

- 8: Inhibit the session being marked as idle

- 16: Inhibit auto-mounting removable media for the session

The returned cookie is used to uniquely identify this request. It should be used as an argument to #Uninhibit() in order to remove the request.

`IN s `app_id``:

  The application identifier, optional

`IN u `ignored``:

  An ignored parameter, which exists only to make this API backwards-compatible with older versions of GNOME

`IN s `reason``:

  The reason for the inhibit

`IN u `flags``:

  Flags that specify what should be inhibited

`OUT u `inhibit_cookie``:

  The cookie

### The Uninhibit() method

    Uninhibit (IN  u inhibit_cookie);

Cancel a previous call to #Inhibit(), identified by the cookie.

`IN u `inhibit_cookie``:

  The cookie

### The IsInhibited() method

    IsInhibited (IN  u flags,
                 OUT b is_inhibited);

Determine if operation(s) specified by the flags are currently inhibited. Flags are same as those accepted by the #Inhibit() method.

`IN u `flags``:

  Flags that specify what should be inhibited

`OUT b `is_inhibited``:

  TRUE if any of the operations in `flags` are inhibited

### The GetInhibitors() method

    GetInhibitors (OUT ao inhibitors);

This gets a list of all the inhibitors that are currently known to the session manager. Each inhibitor ID is a D-Bus object path to the object that implements the Inhibitor interface

`OUT ao `inhibitors``:

  an array of inhibitor IDs

### The Shutdown() method

    Shutdown ();

Request a shutdown dialog.

### The Reboot() method

    Reboot ();

Request a reboot dialog.

### The Suspend() method

    Suspend ();

Request that the system goes to suspend, or whatever other sleep states are available and appropriate for the hardware. Note that this is not suitible for non-interactive use-cases, like automatic power management!

### The CanShutdown() method

    CanShutdown (OUT u availability);

`OUT u `availability``:

### The CanReboot() method

    CanReboot (OUT u availability);

`OUT u `availability``:

### The CanSuspend() method

    CanSuspend (OUT u availability);

`OUT u `availability``:

### The SetRebootToFirmwareSetup() method

    SetRebootToFirmwareSetup (IN  b enable);

Allows the caller to indicate to the system's firmware to boot into setup mode

`IN b `enable``:

  Whether we should reboot into setup

### The CanRebootToFirmwareSetup() method

    CanRebootToFirmwareSetup (OUT b is_available);

Allows the caller to determine whether or not it's okay to show a reboot to firmware option in the UI

`OUT b `is_available``:

  True if boot into setup mode is available to the user, false otherwise

### The Logout() method

    Logout (IN  u mode);

Request a log out dialog.

You may pass the following flags into `mode`, and they can be bitwise or'ed together:

- 0: Normal

- 1: No confirmation interface should be shown.

- 2: Forcefully logout. No confirmation will be shown and any inhibitors will be ignored.

`IN u `mode``:

  The type of logout that is being requested

### The IsSessionRunning() method

    IsSessionRunning (OUT b running);

Allows the caller to determine whether the session is running or not. Returns false if the session is initializing, or shutting down.

`OUT b `running``:

  True if the session is running, false otherwise.

## Signal Details

### The "ClientAdded" signal

    ClientAdded (o id);

Emitted when a client has been added to the session manager.

`o `id``:

  The object path for the added client

### The "ClientRemoved" signal

    ClientRemoved (o id);

Emitted when a client has been removed from the session manager.

`o `id``:

  The object path for the removed client

### The "InhibitorAdded" signal

    InhibitorAdded (o id);

Emitted when an inhibitor has been added to the session manager.

`o `id``:

  The object path for the added inhibitor

### The "InhibitorRemoved" signal

    InhibitorRemoved (o id);

Emitted when an inhibitor has been removed from the session manager.

`o `id``:

  The object path for the removed inhibitor

### The "SessionRunning" signal

    SessionRunning ();

Emitted when the session is done initializing.

### The "SessionOver" signal

    SessionOver ();

Emitted when the session is about to end.

## Property Details

### The "SessionName" property

    SessionName  readable   s

The name of the session that has been loaded.

### The "Renderer" property

    Renderer  readable   s

Starting in GNOME 49, this property always returns an empty string. You should instead use the `GPUs` property on the net.hadess.SwitcherooControl service instead.

### Warning

The "Renderer" property is deprecated.

### The "SessionIsActive" property

    SessionIsActive  readable   b

If true, the session is currently in the foreground and available for user input.

### The "InhibitedActions" property

    InhibitedActions  readable   u

A bitmask of flags to indicate which actions are inhibited. See #Inhibit() for a list of possible values.

### The "RestoreSupported" property

    RestoreSupported  readable   b

Communicates whether the session supports the save/restore mechanism.

Prev | Up | Next
Part II. Internal D-Bus API | Home | org.gnome.SessionManager.ClientPrivate