Session lock
此协议允许拥有特权的 Wayland 客户端锁定会话并在会话锁定期间显示任意图形。
compositor 可以选择将此协议限制为由 compositor 本身启动的特定客户端，或者向所有特权客户端公开，这是 compositor 策略。
客户端负责执行身份验证并在应解锁会话时通知 compositor。如果客户端在会话锁定时终止，会话将保持锁定状态，可能会永久锁定，这取决于 compositor 策略。
本文档中的关键字“must”、“must not”、“required”、“shall”、“shall not”、“should”、“should not”、“recommended”、“may”和“optional”将按照 IETF RFC 2119 中的描述进行解释。
警告！此文件中描述的协议目前处于测试阶段。向后兼容的更改可能会与相应的接口版本增加一起添加。向后不兼容的更改只能通过创建扩展的新主要版本来完成。
此接口用于请求锁定会话。
destroy()
这会通知 compositor 会话锁管理器对象将不再使用。通过此接口创建的现有对象仍然有效。
lock(id: new_id<ext_session_lock_v1>)
参数 | 类型 | 描述 |
|---|---|---|
| id | new_id<ext_session_lock_v1> |
此请求创建一个会话锁并要求 compositor 锁定会话。compositor 将响应此请求并在创建的对象上发送 ext_session_lock_v1.locked 或 ext_session_lock_v1.finished 事件。
响应此对象的创建，compositor 必须发送 locked 或 finished 事件。
locked 事件表明会话已被锁定。这意味着 compositor 必须停止向普通客户端渲染并提供输入。相反，compositor 必须使用不透明颜色空白所有输出，以便其正常内容被完全隐藏。
在会话锁定期间应该渲染的唯一表面是通过此接口创建的锁表面，并且 compositor 可以自行决定是否渲染特殊的特权表面，例如输入法或桌面 shell UI 的一部分。
在新的“锁定”帧（来自会话锁表面或 compositor 自身的空白）提交之前，不得发送 locked 事件。
finished 事件表明会话无法被锁定，该客户端失去其焦点，或者是 compositor 决定终止会话锁定。在收到 finished 事件时，客户端必须立即销毁此对象并在适用的情况下使用相同的接口重试锁操作。
一旦发送了 locked 事件，它就是不可撤销的。如果在客户端由于 compositor 断开连接或崩溃而被强制终止的情况下仍持有不可撤销的锁，或者此对象被销毁，则该会话应保持锁定状态。可以通过重新连接相同或另一个客户端来进行重新获取锁操作，以重新夺回锁对象。
destroy()
这会通知 compositor 会话锁对象将不再使用。通过此接口创建的现有对象仍然有效。
get_lock_surface(id: new_id<ext_session_lock_surface_v1>, surface: object<wl_surface>, output: object<wl_output>)
参数 | 类型 | 描述 |
|---|---|---|
| id | new_id<ext_session_lock_surface_v1> | |
| surface | object<wl_surface> | |
| output | object<wl_output> |
客户端通过发送此请求并提供目标 wl_output 对象来创建与该输出相关联的锁表面。
unlock_and_destroy()
此请求表明会话应该被解锁，同时销毁相关的锁对象。compositor 必须接收解锁请求并在适当的条件满足时恢复正常状态。
error { invalid_destroy, invalid_unlock, role, duplicate_output, already_constructed }
参数 | 值 | 描述 |
|---|---|---|
| invalid_destroy | 0 | 在会话锁定期间尝试销毁会话锁 |
| invalid_unlock | 1 | 请求解锁但从未发送过 locked 事件 |
| role | 2 | 给定的 wl_surface 已经具有角色 |
| duplicate_output | 3 | 给定的 output 已经有一个锁表面 |
| already_constructed | 4 | 给定的 wl_surface 已经附加或提交了 buffer |
此对象表示在锁定状态期间显示内容的表面。这是一个特殊的表面，仅在 ext_session_lock_v1 对象的上下文中有效。
ack_configure(serial: uint)
参数 | 类型 | 描述 |
|---|---|---|
| serial | uint | serial from the configure event |
确认已经处理了一个配置事件。这在后续的 wl_surface.commit 中被确认。
compositor 发送此事件以建议表面所需的宽度和高度。
参数 | 值 | 描述 |
|---|---|---|
| commit_before_first_ack | 0 | 在首次 ack_configure 请求之前提交了表面 |
| null_buffer | 1 | 提交了空 buffer 的表面 |
| dimensions_mismatch | 2 | 未能匹配已确认的宽度和高度 |
| invalid_serial | 3 | ack_configure 中提供的 serial 无效 |
合成器支持
Cage  | COSMIC  | GameScope  | Hyprland  | Jay | KWin  | Labwc  | Louvre  | Mir  | Muffin  | Mutter  | niri  | phoc  | river  | Sway  | Treeland  | Wayfire  | Weston  | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ext_session_lock_manager_v1 | x | 1 | x | 1 | 1 | x | 1 | 1 | 1 | x | x | 1 | x | 1 | 1 | 1 | 1 | x |
Copyright
Copyright 2021 Isaac Freund
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.