node /org/freedesktop/login1/session/1 {
interface org.freedesktop.login1.Session {
methods:
Terminate();
Activate();
Lock();
Unlock();
SetIdleHint(in b idle);
SetLockedHint(in b locked);
Kill(in s who,
in i signal_number);
TakeControl(in b force);
ReleaseControl();
SetType(in s type);
TakeDevice(in u major,
in u minor,
out h fd,
out b inactive);
ReleaseDevice(in u major,
in u minor);
PauseDeviceComplete(in u major,
in u minor);
SetBrightness(in s subsystem,
in s name,
in u brightness);
signals:
PauseDevice(u major,
u minor,
s type);
ResumeDevice(u major,
u minor,
h fd);
Lock();
Unlock();
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Id = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly (uo) User = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Name = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t Timestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t TimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u VTNr = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly (so) Seat = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s TTY = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Display = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly b Remote = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s RemoteHost = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s RemoteUser = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Service = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Desktop = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Scope = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Leader = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Audit = ...;
readonly s Type = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Class = '...';
readonly b Active = ...;
readonly s State = '...';
readonly b IdleHint = ...;
readonly t IdleSinceHint = ...;
readonly t IdleSinceHintMonotonic = ...;
readonly b LockedHint = ...;
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
Methods
Terminate(), Activate(), Lock(), Unlock(), and Kill() work
similarly to the respective calls on the Manager object.
SetIdleHint() is called by the session object to update the idle
state of the session whenever it changes.
TakeControl() allows a process to take exclusive managed device
access-control for that session. Only one D-Bus connection can be
a controller for a given session at any time. If the force
argument is set (root only), an existing controller is kicked out
and replaced. Otherwise, this method fails if there is already a
controller. Note that this method is limited to D-Bus users with
the effective UID set to the user of the session or root.
ReleaseControl() drops control of a given session. Closing the
D-Bus connection implicitly releases control as well. See
TakeControl() for more information. This method also releases all
devices for which the controller requested ownership via
TakeDevice().
SetType() allows the type of the session to be changed
dynamically. It can only be called by session's current
controller. If TakeControl() has not been called, this method
will fail. In addition, the session type will be reset to its
original value once control is released, either by calling
ReleaseControl() or closing the D-Bus connection. This should
help prevent a session from entering an inconsistent state, for
example if the controller crashes. The only argument type is the
new session type.
TakeDevice() allows a session controller to get a file descriptor
for a specific device. Pass in the major and minor numbers of the
character device and systemd-logind will return a file descriptor
for the device. Only a limited set of device-types is currently
supported (but may be extended). systemd-logind automatically
mutes the file descriptor if the session is inactive and resumes
it once the session is activated again. This guarantees that a
session can only access session devices if the session is active.
Note that this revoke/resume mechanism is asynchronous and may
happen at any given time. This only works on devices that are
attached to the seat of the given session. A process is not
required to have direct access to the device node.
systemd-logind only requires you to be the active session
controller (see TakeControl()). Also note that any device can
only be requested once. As long as you don't release it, further
TakeDevice() calls will fail.
ReleaseDevice() releases a device again (see TakeDevice()). This
is also implicitly done by ReleaseControl() or when closing the
D-Bus connection.
PauseDeviceComplete() allows a session controller to
synchronously pause a device after receiving a
PauseDevice("pause") signal. Forced signals (or after an internal
timeout) are automatically completed by systemd-logind
asynchronously.
SetLockedHint() may be used to set the "locked hint" to locked,
i.e. information whether the session is locked. This is intended
to be used by the desktop environment to tell systemd-logind when
the session is locked and unlocked.
SetBrightness() may be used to set the display brightness. This
is intended to be used by the desktop environment and allows
unprivileged programs to access hardware settings in a controlled
way. The subsystem parameter specifies a kernel subsystem, either
"backlight" or "leds". The name parameter specifies a device name
under the specified subsystem. The brightness parameter specifies
the brightness. The range is defined by individual drivers, see
/sys/class/subsystem/name/max_brightness.
Signals
The active session controller exclusively gets PauseDevice and
ResumeDevice events for any device it requested via TakeDevice().
They notify the controller whenever a device is paused or
resumed. A device is never resumed if its session is inactive.
Also note that PauseDevice signals are sent before the
PropertyChanged signal for the Active state. The inverse is true
for ResumeDevice. A device may remain paused for unknown reasons
even though the Session is active.
A PauseDevice signal carries the major and minor numbers and a
string describing the type as arguments. force means the device
was already paused by systemd-logind and the signal is only an
asynchronous notification. pause means systemd-logind grants you
a limited amount of time to pause the device. You must respond to
this via PauseDeviceComplete(). This synchronous pausing
mechanism is used for backwards-compatibility to VTs and
systemd-logind is free to not make use of it. It is also free to
send a forced PauseDevice if you don't respond in a timely manner
(or for any other reason). gone means the device was unplugged
from the system and you will no longer get any notifications
about it. There is no need to call ReleaseDevice(). You may call
TakeDevice() again if a new device is assigned the major+minor
combination.
ResumeDevice is sent whenever a session is active and a device is
resumed. It carries the major/minor numbers as arguments and
provides a new open file descriptor. You should switch to the new
descriptor and close the old one. They are not guaranteed to have
the same underlying open file descriptor in the kernel (except
for a limited set of device types).
Whenever Active or the idle state changes, PropertyChanged
signals are sent out to which clients can subscribe.
Lock/Unlock is sent when the session is asked to be
screen-locked/unlocked. A session manager of the session should
listen to this signal and act accordingly. This signal is sent
out as a result of the Lock() and Unlock() methods, respectively.
Properties
Id encodes the session ID.
User encodes the user ID of the user this session belongs to.
This is a structure consisting of the Unix UID and the object
path.
Name encodes the user name.
Timestamp and TimestampMonotonic encode the microseconds since
the epoch when the session was created, in CLOCK_REALTIME or
CLOCK_MONOTONIC, respectively.
VTNr encodes the virtual terminal number of the session if there
is any, 0 otherwise.
Seat encodes the seat this session belongs to if there is any.
This is a structure consisting of the ID and the seat object
path.
TTY encodes the kernel TTY path of the session if this is a text
login. If not this is an empty string.
Display encodes the X11 display name if this is a graphical
login. If not, this is an empty string.
Remote encodes whether the session is local or remote.
RemoteHost and RemoteUser encode the remote host and user if this
is a remote session, or an empty string otherwise.
Service encodes the PAM service name that registered the session.
Desktop describes the desktop environment running in the session
(if known).
Scope contains the systemd scope unit name of this session.
Leader encodes the PID of the process that registered the
session.
Audit encodes the Kernel Audit session ID of the session if
auditing is available.
Type encodes the session type. It's one of "unspecified" (for
cron PAM sessions and suchlike), "tty" (for text logins) or
"x11"/"mir"/"wayland" (for graphical logins).
Class encodes the session class. It's one of "user" (for normal
user sessions), "greeter" (for display manager pseudo-sessions),
or "lock-screen" (for display lock screens).
Active is a boolean that is true if the session is active, i.e.
currently in the foreground. This field is semi-redundant due to
State.
State encodes the session state and one of "online", "active", or
"closing". See sd_session_get_state(3) for more information about
the states.
IdleHint, IdleSinceHint, and IdleSinceHintMonotonic encapsulate
the idle hint state of this session, similarly to how the
respective properties on the manager object do it for the whole
system.
LockedHint shows the locked hint state of this session, as set by
the SetLockedHint() method described above.
