GNOME Session 3.22.3 Documentation

William Jon McCann


            
          

Version 3.22.3


Table of Contents

I. Reference
I. D-Bus API Reference
org.gnome.SessionManager — SessionManager interface
org.gnome.SessionManager.Client — Client interface
org.gnome.SessionManager.ClientPrivate — ClientPrivate interface
org.gnome.SessionManager.Inhibitor — Inhibitor interface
org.gnome.SessionManager.Presence — Presence interface
Index

Part I. Reference

Table of Contents

I. D-Bus API Reference
org.gnome.SessionManager — SessionManager interface
org.gnome.SessionManager.Client — Client interface
org.gnome.SessionManager.ClientPrivate — ClientPrivate interface
org.gnome.SessionManager.Inhibitor — Inhibitor interface
org.gnome.SessionManager.Presence — Presence interface

D-Bus API Reference


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

Table of Contents

org.gnome.SessionManager — SessionManager interface
org.gnome.SessionManager.Client — Client interface
org.gnome.SessionManager.ClientPrivate — ClientPrivate interface
org.gnome.SessionManager.Inhibitor — Inhibitor interface
org.gnome.SessionManager.Presence — Presence interface

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

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 spefify 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

Logout ()

Logout (in  'u' mode)

Request a logout dialog

Allowed values for the mode parameter are:

  • 0: Normal.
  • 1: No confirmation inferface 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 ()

Inititate 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
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 ()
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 ()
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 ()