Treeland app ID resolver v2
Internal bridge between treeland and the user-session treeland-session-helper. Treeland is a multi-user compositor and does not host per-user-session D-Bus itself, so it asks treeland-session-helper, running in the user session, to map a process (identified by a pidfd) to its application identifier and sandbox engine name. treeland-session-helper answers over this Wayland protocol; it in turn resolves the request through D-Bus with dde-application-manager. This protocol is only for that dedicated treeland-session-helper bridge, not a general application-developer API, and regular clients must not bind it.
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_app_id_resolver_manager_v2
Factory global for creating resolver objects. Typically exactly one treeland-session-helper instance (a Wayland client in the user session) binds this interface and serves identification requests coming from the compositor. Only the treeland-session-helper bridge should bind this global; regular application clients must not use it.
destroy()
Destroy the manager object. Existing resolver objects remain valid and must be destroyed independently.
get_resolver(id: new_id<treeland_app_id_resolver_v2>)
Argument | Type | Description |
|---|---|---|
| id | new_id<treeland_app_id_resolver_v2> |
Create a resolver object. Only one resolver may be registered per session. Treeland is a multi-user compositor; different user sessions may each register their own resolver. If a resolver is already bound in the same session, the compositor will raise the resolver_already_exists error and will not create a new resolver object.
error { resolver_already_exists }
Argument | Value | Description |
|---|---|---|
| resolver_already_exists | 0 | a resolver is already registered in this session |
treeland_app_id_resolver_v2
Per-session resolver object created through the manager. The compositor sends identify_request events carrying a pidfd, and treeland-session-helper must respond exactly once per request via the respond request. If resolution fails it responds with an empty app_id.
destroy()
Destroy the resolver object. The compositor will no longer send identify_request events after this request is processed.
respond(request_id: uint, app_id: string, sandbox_engine_name: string)
Argument | Type | Description |
|---|---|---|
| request_id | uint | the request ID from identify_request |
| app_id | string | the resolved application identifier, or empty string on failure |
| sandbox_engine_name | string | the sandbox engine or security context name |
Respond to a prior identify_request event. treeland-session-helper must call this exactly once for each identify_request. If the application cannot be identified, respond with an empty app_id. The sandbox_engine_name must always be provided and describes the security context in which the process is running (container, sandbox, etc.).
identify_request(request_id: uint, pidfd: fd)
Argument | Type | Description |
|---|---|---|
| request_id | uint | monotonic id generated by compositor |
| pidfd | fd | pidfd referencing the target process |
Sent by the compositor to ask treeland-session-helper to resolve a process to an application identifier. The compositor emits this event each time it needs to identify a process for which it does not already have a cached result. treeland-session-helper must respond exactly once via the respond request using the provided request_id. Failure to respond in a timely manner may cause the compositor to treat the process as unidentified.
Compositor Support
Copyright
SPDX-FileCopyrightText: 2025 - 2026 UnionTech Software Technology Co., Ltd. SPDX-License-Identifier: MIT