# GNOME Session 44.0 Documentation

### William Jon McCann

`<jmccann@redhat.com>`

Version 44.0

# Part I. Reference

# D-Bus API Reference

This API is not yet stable and is likely to change in the future.

## Name

org.gnome.SessionManager — SessionManager interface

## 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'  client_startup_id,
                                 out 'o'  client_id)
    UnregisterClient            (in  'o'  client_id)
    Inhibit                     (in  's'  app_id,
                                 in  'u'  toplevel_xid,
                                 in  's'  reason,
                                 in  'u'  flags,
                                 out 'u'  inhibit_cookie)
    Uninhibit                   (in  'u'  inhibit_cookie)
    IsInhibited                 (in  'u'  flags,
                                 out 'b'  is_inhibited)
    GetClients                  (out 'ao' clients)
    GetInhibitors               (out 'ao' inhibitors)
    IsAutostartConditionHandled (in  's'  condition,
                                 out 'b'  handled)
    Shutdown                    ()
    Reboot                      ()
    CanShutdown                 (out 'b'  is_available)
    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      ()

## Implemented Interfaces

Objects implementing org.gnome.SessionManager also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

## Properties

    'SessionName'      read      's'
    'Renderer'         read      's'
    'SessionIsActive'  read      'b'
    'InhibitedActions' read      'u'

## Description

## Details

### Setenv ()

    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.

`variable`:
  The variable name
`value`:
  The value

### GetLocale ()

    GetLocale (in  'i' category,
               out 's' value)

Reads the current state of the specific locale category.

`category`:
  The locale category
`value`:
  The value

### InitializationError ()

    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.

`message`:
  The error message
`fatal`:
  Whether the error should be treated as fatal

### Initialized ()

    Initialized ()

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

### RegisterClient ()

    RegisterClient (in  's' app_id,
                    in  's' client_startup_id,
                    out 'o' client_id)

Register the caller as a Session Management client.

`app_id`:
  The application identifier
`client_startup_id`:
  Client startup identifier
`client_id`:
  The object path of the newly registered client

### UnregisterClient ()

    UnregisterClient (in  'o' client_id)

Unregister the specified client from Session Management.

`client_id`:
  The object path of the client

### Inhibit ()

    Inhibit (in  's' app_id,
             in  'u' toplevel_xid,
             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.

Reasons should be short and to the point.

The flags parameter must include at least one of the following:

- 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

Values for flags may be bitwise or'ed together.

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.

`app_id`:
  The application identifier
`toplevel_xid`:
  The toplevel X window identifier
`reason`:
  The reason for the inhibit
`flags`:
  Flags that specify what should be inhibited
`inhibit_cookie`:
  The cookie

### Uninhibit ()

    Uninhibit (in  'u' inhibit_cookie)

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

`inhibit_cookie`:
  The cookie

### IsInhibited ()

    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.

`flags`:
  Flags that specify what should be inhibited
`is_inhibited`:
  Returns TRUE if any of the operations in the bitfield flags are inhibited

### GetClients ()

    GetClients (out 'ao' clients)

This gets a list of all the Clients that are currently known to the session manager.

Each Client ID is an D-Bus object path for the object that implements the Client interface.

`clients`:
  an array of client IDs

See also: org.gnome.SessionManager.Client

### GetInhibitors ()

    GetInhibitors (out 'ao' inhibitors)

This gets a list of all the Inhibitors that are currently known to the session manager.

Each Inhibitor ID is an D-Bus object path for the object that implements the Inhibitor interface.

`inhibitors`:
  an array of inhibitor IDs

See also: org.gnome.SessionManager.Inhibitor

### IsAutostartConditionHandled ()

    IsAutostartConditionHandled (in  's' condition,
                                 out 'b' handled)

Allows the caller to determine whether the session manager is handling changes to the specified autostart condition.

`condition`:
  The autostart condition string
`handled`:
  True if condition is handled, false otherwise

### Shutdown ()

    Shutdown ()

Request a shutdown dialog.

### Reboot ()

    Reboot ()

Request a reboot dialog.

### CanShutdown ()

    CanShutdown (out 'b' is_available)

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

`is_available`:
  True if shutdown is available to the user, false otherwise

### SetRebootToFirmwareSetup ()

    SetRebootToFirmwareSetup (in  'b' enable)

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

`enable`:
  Whether we should reboot into setup

### CanRebootToFirmwareSetup ()

    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

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

### Logout ()

    Logout (in  'u' mode)

Request a logout dialog

Allowed values for the mode parameter are:

- 0: Normal.
- 1: No confirmation interface should be shown.
- 2: Forcefully logout. No confirmation will be shown and any inhibitors will be ignored.

Values for flags may be bitwise or'ed together.

`mode`:
  The type of logout that is being requested

### IsSessionRunning ()

    IsSessionRunning (out 'b' running)

Allows the caller to determine whether the session manager has entered the Running phase, in case the client missed the SessionRunning signal.

`running`:
  True if the session has entered the Running phase, false otherwise

## Signal Details

### The ClientAdded signal

    ClientAdded ('o' id)

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

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

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

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

`id`:
  The object path for the removed inhibitor

### The SessionRunning signal

    SessionRunning ()

Indicates the session has entered the Running phase.

### The SessionOver signal

    SessionOver ()

Indicates the session is about to end.

## Property Details

### The "SessionName" property

    'SessionName'  read      's'

The name of the session that has been loaded.

### The "Renderer" property

    'Renderer'  read      's'

The renderer for the session that has been loaded. At the moment this supports GL and GLES, and is only used for the X session.

### The "SessionIsActive" property

    'SessionIsActive'  read      'b'

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

### The "InhibitedActions" property

    'InhibitedActions'  read      'u'

A bitmask of flags to indicate which actions are inhibited. See the Inhibit() function's description for a list of possible values.

## Name

org.gnome.SessionManager.Client — Client interface

## Methods

    GetAppId            (out 's' app_id)
    GetStartupId        (out 's' startup_id)
    GetRestartStyleHint (out 'u' hint)
    GetUnixProcessId    (out 'u' pid)
    GetStatus           (out 'u' status)
    Stop                ()

## Implemented Interfaces

Objects implementing org.gnome.SessionManager.Client also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

## Description

## Details

### GetAppId ()

    GetAppId (out 's' app_id)

Return the application ID associated with this client.

`app_id`:
  The identifier for the associated application

### GetStartupId ()

    GetStartupId (out 's' startup_id)

Return the startup ID associated with this client.

`startup_id`:
  The startup identifier

### GetRestartStyleHint ()

    GetRestartStyleHint (out 'u' hint)

Return the restart style hint for this client.

`hint`:
  The restart style hint

### GetUnixProcessId ()

    GetUnixProcessId (out 'u' pid)

Return the Unix process identifier for this client.

`pid`:
  The Unix process identifier

### GetStatus ()

    GetStatus (out 'u' status)

Return the status of this client.

`status`:
  The client status

### Stop ()

    Stop ()

Initiate a request to terminate this application via XSMP.

## Name

org.gnome.SessionManager.ClientPrivate — ClientPrivate interface

## Methods

    EndSessionResponse (in  'b' is_ok,
                        in  's' reason)

## Signals

    Stop             ()
    QueryEndSession  ('u' flags)
    EndSession       ('u' flags)
    CancelEndSession ()

## Implemented Interfaces

Objects implementing org.gnome.SessionManager.ClientPrivate also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

## Description

## Details

### EndSessionResponse ()

    EndSessionResponse (in  'b' is_ok,
                        in  's' reason)

This method should be used by the client in response to the `QueryEndSession` and `EndSession` signals.

`is_ok`:
  Whether or not it is OK to preceed
`reason`:
  The reason string

## Signal Details

### The Stop signal

    Stop ()

The client should stop and remove itself from the session in response to this signal.

### The QueryEndSession signal

    QueryEndSession ('u' flags)

This signal is used to inform the client that the session is about to end. The client must respond by calling `EndSessionResponse` within one second of the signal emission.

The flags may include:

- 1: Logout is forced. `EndSessionResponse` reason and any inhibit from client will be ignored.

If the client responds with an EndSessionResponse is-ok argument equal to FALSE and a reason then this reason may be displayed to the user.

The client must not attempt to perform any actions or interact with the user in response to this signal. Any actions required for a clean shutdown should take place in response to the `EndSession` signal.

The client should limit operations until either a `EndSession` `CancelEndSession` signal is received.

`flags`:
  Flags

### The EndSession signal

    EndSession ('u' flags)

This signal is used to inform the client that the session is about to end. The client must respond by calling `EndSessionResponse` within ten seconds of the signal emission.

The client must not attempt to interact with the user in response to this signal. The application will be given a maxium of ten seconds to perform any actions required for a clean shutdown.

`flags`:
  Flags

### The CancelEndSession signal

    CancelEndSession ()

This signal indicates to the client that a previous emission of `QueryEndSession` has been cancelled. The client should resume normal operations.

## Name

org.gnome.SessionManager.Inhibitor — Inhibitor interface

## Methods

    GetAppId       (out 's' app_id)
    GetClientId    (out 'o' client_id)
    GetReason      (out 's' reason)
    GetFlags       (out 'u' flags)
    GetToplevelXid (out 'u' xid)

## Implemented Interfaces

Objects implementing org.gnome.SessionManager.Inhibitor also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

## Description

## Details

### GetAppId ()

    GetAppId (out 's' app_id)

Return the application ID associated with this inhibit.

`app_id`:
  The identifier for the associated application

### GetClientId ()

    GetClientId (out 'o' client_id)

Return the client object path associated with this inhibit.

`client_id`:
  The object path of the associated client

### GetReason ()

    GetReason (out 's' reason)

Return the reason for the inhibit

`reason`:
  The reason for the inhibit

### GetFlags ()

    GetFlags (out 'u' flags)

Return the flags that determine the scope of the inhibit

`flags`:
  The flags that determine the scope of the inhibit

### GetToplevelXid ()

    GetToplevelXid (out 'u' xid)

Return the X11 toplevel window identifier associated with this inhibit. Zero if not set.

`xid`:
  X11 toplevel window identifier associated with this inhibit. Zero if not set.

## Name

org.gnome.SessionManager.Presence — Presence interface

## Methods

    SetStatus     (in  'u' status)
    SetStatusText (in  's' status_text)

## Signals

    StatusChanged     ('u' status)
    StatusTextChanged ('s' status_text)

## Implemented Interfaces

Objects implementing org.gnome.SessionManager.Presence also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

## Properties

    'status'      readwrite 'u'
    'status-text' readwrite 's'

## Description

## Details

### SetStatus ()

    SetStatus (in  'u' status)

Set the status value of the session.

`status`:
  The status value

### SetStatusText ()

    SetStatusText (in  's' status_text)

Set the descriptive status text for the session.

`status_text`:
  The descriptive status for the session.

## Signal Details

### The StatusChanged signal

    StatusChanged ('u' status)

Indicates that the session status value has changed.

`status`:
  The new status value

### The StatusTextChanged signal

    StatusTextChanged ('s' status_text)

Indicates that the descriptive session status text has changed.

`status_text`:
  The new status text

## Property Details

### The "status" property

    'status'  readwrite 'u'

The status of the session.

The status parameter must be one of the following:

- 0: Available
- 1: Invisible
- 2: Busy
- 3: Idle

### The "status-text" property

    'status-text'  readwrite 's'

The descriptive status for the session.

# Index

### C

CancelEndSession
  org.gnome.SessionManager.ClientPrivate, The CancelEndSession signal
CanRebootToFirmwareSetup
  org.gnome.SessionManager, CanRebootToFirmwareSetup ()
CanShutdown
  org.gnome.SessionManager, CanShutdown ()
ClientAdded
  org.gnome.SessionManager, The ClientAdded signal
ClientRemoved
  org.gnome.SessionManager, The ClientRemoved signal

### E

EndSession
  org.gnome.SessionManager.ClientPrivate, The EndSession signal
EndSessionResponse
  org.gnome.SessionManager.ClientPrivate, EndSessionResponse ()

### G

GetAppId
  org.gnome.SessionManager.Client, GetAppId ()
  org.gnome.SessionManager.Inhibitor, GetAppId ()
GetClientId
  org.gnome.SessionManager.Inhibitor, GetClientId ()
GetClients
  org.gnome.SessionManager, GetClients ()
GetFlags
  org.gnome.SessionManager.Inhibitor, GetFlags ()
GetInhibitors
  org.gnome.SessionManager, GetInhibitors ()
GetLocale
  org.gnome.SessionManager, GetLocale ()
GetReason
  org.gnome.SessionManager.Inhibitor, GetReason ()
GetRestartStyleHint
  org.gnome.SessionManager.Client, GetRestartStyleHint ()
GetStartupId
  org.gnome.SessionManager.Client, GetStartupId ()
GetStatus
  org.gnome.SessionManager.Client, GetStatus ()
GetToplevelXid
  org.gnome.SessionManager.Inhibitor, GetToplevelXid ()
GetUnixProcessId
  org.gnome.SessionManager.Client, GetUnixProcessId ()

### I

Inhibit
  org.gnome.SessionManager, Inhibit ()
InhibitedActions
  org.gnome.SessionManager, The "InhibitedActions" property
InhibitorAdded
  org.gnome.SessionManager, The InhibitorAdded signal
InhibitorRemoved
  org.gnome.SessionManager, The InhibitorRemoved signal
InitializationError
  org.gnome.SessionManager, InitializationError ()
Initialized
  org.gnome.SessionManager, Initialized ()
IsAutostartConditionHandled
  org.gnome.SessionManager, IsAutostartConditionHandled ()
IsInhibited
  org.gnome.SessionManager, IsInhibited ()
IsSessionRunning
  org.gnome.SessionManager, IsSessionRunning ()

### L

Logout
  org.gnome.SessionManager, Logout ()

### Q

QueryEndSession
  org.gnome.SessionManager.ClientPrivate, The QueryEndSession signal

### R

Reboot
  org.gnome.SessionManager, Reboot ()
RegisterClient
  org.gnome.SessionManager, RegisterClient ()
Renderer
  org.gnome.SessionManager, The "Renderer" property

### S

SessionIsActive
  org.gnome.SessionManager, The "SessionIsActive" property
SessionName
  org.gnome.SessionManager, The "SessionName" property
SessionOver
  org.gnome.SessionManager, The SessionOver signal
SessionRunning
  org.gnome.SessionManager, The SessionRunning signal
Setenv
  org.gnome.SessionManager, Setenv ()
SetRebootToFirmwareSetup
  org.gnome.SessionManager, SetRebootToFirmwareSetup ()
SetStatus
  org.gnome.SessionManager.Presence, SetStatus ()
SetStatusText
  org.gnome.SessionManager.Presence, SetStatusText ()
Shutdown
  org.gnome.SessionManager, Shutdown ()
status
  org.gnome.SessionManager.Presence, The "status" property
status-text
  org.gnome.SessionManager.Presence, The "status-text" property
StatusChanged
  org.gnome.SessionManager.Presence, The StatusChanged signal
StatusTextChanged
  org.gnome.SessionManager.Presence, The StatusTextChanged signal
Stop
  org.gnome.SessionManager.Client, Stop ()
  org.gnome.SessionManager.ClientPrivate, The Stop signal

### U

Uninhibit
  org.gnome.SessionManager, Uninhibit ()
UnregisterClient
  org.gnome.SessionManager, UnregisterClient ()