Treeland screensaver v2

screensaver D-Bus relay for treeland

Internal protocol that relays org.freedesktop.ScreenSaver inhibit/uninhibit requests between treeland and a per-user-session helper, because a multi-user compositor does not host per-user-session D-Bus itself.

The key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" in this document are to be interpreted as described in RFC 2119.

Warning! This protocol is EXPERIMENTAL and under active development. It may change at any time, including in backward-incompatible ways, without incrementing the interface major version and without prior notice. No compatibility guarantees of any kind are provided. Clients and compositors must track the upstream definition in treeland-protocols and must not rely on the current interface names, requests, events, or semantics remaining stable across releases.

treeland screensaver DBus relay

This interface is an internal relay between treeland and a privileged helper that implements the org.freedesktop.ScreenSaver D-Bus interface. Treeland is a multi-user compositor and does not host per-user-session D-Bus itself, so the org.freedesktop.ScreenSaver Inhibit/UnInhibit calls are forwarded over this Wayland protocol to a helper running in the user session, which then performs the actual idle-inhibit bookkeeping.

Only that dedicated relay helper should bind this global. Regular applications must NOT use this protocol to inhibit idleness; they should use the upstream zwp_idle_inhibit_manager_v1 protocol instead, which treeland exposes for normal clients.

The relay helper calls inhibit to register an inhibit on behalf of a D-Bus caller and uninhibit (or disconnects the bound object) to release it. If the bound object is destroyed, the inhibit associated with it is automatically released. At most one inhibit is active per bound object at a time; calling inhibit while an inhibit is already active raises already_inhibited, and calling uninhibit with no active inhibit raises not_yet_inhibited. Call uninhibit before inhibit to update application_name and reason.

destroy()
destroy the screensaver relay object

Destroy the bound treeland_screensaver_v2 object. Any inhibit previously registered through this object is released as if uninhibit had been called, and the relay helper must stop holding the corresponding org.freedesktop.ScreenSaver inhibit on the D-Bus caller's behalf.

inhibit(application_name: string, reason_for_inhibit: string)
Argument
Type
Description
application_namestring
name of the application requesting the inhibit
reason_for_inhibitstring
human-readable reason for the inhibit request
Inhibit idleness

Inhibit idleness with given application_name and reason_for_inhibit.

uninhibit()
Uninhibit idleness

Uninhibit idleness previously inhibited by inhibit request.

Argument
Value
Description
not_yet_inhibited0
Trying to uninhibit but no active inhibit existed
already_inhibited1
Trying to inhibit with an active inhibit existed

Compositor Support

No compositor support found

SPDX-FileCopyrightText: 2025 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT