treeland-protocols: add wine wayland protocols

[wineee]

Add the first cut of the Wine-specific Wayland protocol split for Treeland.

• add treeland_wine_window_management_v1 for SetWindowPos-style geometry and Z-order control
• add treeland_wine_window_state_v1 for minimize, activation, attention, and pointer grab state
• register both protocol XML files in the install list

This keeps Wine window management and state control separate so each area can evolve independently while still matching the Windows API model more closely than xdg-shell.

[deepin-ci-robot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[Copilot]

Pull request overview

Adds the initial Wine-specific Wayland protocol split for Treeland, separating privileged window geometry/stacking operations from window state observation/control to better model Windows APIs.

Changes:

• Introduces treeland_wine_window_management_v1 protocol XML for SetWindowPos-style geometry and Z-order control.
• Introduces treeland_wine_window_state_v1 protocol XML for minimize/attention, activation requests, and pointer-grab-like behavior.
• Registers both new protocol XML files for installation via CMake.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
xml/treeland-wine-window-management-v1.xml	New protocol definition for Wine window geometry + stacking/Z-order operations.
xml/treeland-wine-window-state-v1.xml	New protocol definition for Wine window state control (minimize/attention/activate) and pointer grab state.
CMakeLists.txt	Installs the two newly added protocol XML files.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zzxyb]

是否需要一个done事件用来同步客户端这三个事件都发送了？

[wineee]

初始化规定了顺序一定是 window_id -> configure_position -> configure_stacking, 收到 configure_stacking 隐含了 done 语义

[zzxyb]

你的state里面枚举状态太少，是否考虑写的全点？

[wineee]

这里只是缺什么补什么，大部分状态在 xdg-shell 协议里面

[mogoweb]

ok

[mogoweb]

可以根据id，得到 controlled 的toplevel对象吗？

[wineee]

这个客户端自己记录调用 get_window_control 时传入的哪个 toplevel

[deepin-ci-robot]

deepin pr auto review

这是一份为 Wine 应用程序在 Wayland 上实现窗口管理和状态控制的 Wayland 协议扩展代码。总体来说，这份代码结构清晰，文档详尽，遵循了 Wayland 协议的设计规范。以下是对语法逻辑、代码质量、代码性能和代码安全方面的详细审查和改进建议：

1. 语法逻辑

优点：

• XML 结构规范：协议定义严格遵循 Wayland 协议的 XML 格式，<protocol>, <interface>, <request>, <event>, <arg>, <enum> 等标签使用正确。
• 类型定义准确：使用了 new_id, uint, int, object 等正确的 Wayland 类型。
• 枚举逻辑严密：z_order_op 和 activate_reason 的枚举值设计合理，准确映射了 Windows API 的语义。
• 事件与请求的配对：例如 set_position 请求与 configure_position 事件配对，set_z_order 与 configure_stacking 配对，逻辑闭环完整，符合 Wayland 的异步请求-响应模型。
• 错误处理定义：在接口中定义了 error 枚举，明确了协议违规行为（如重复绑定、对象失效等）。

改进建议：

• 版权年份：两个 XML 文件中的版权年份写的是 2026。除非这是为了未来发布而预留的代码，否则建议修改为当前年份（如 2023 或 2024），以避免混淆。
• configure_position 的触发时机：文档中提到 "when the user or compositor moves the window" 时会发送该事件。这需要明确：如果用户通过合成器（Compositor）的装饰器拖动窗口，合成器会发送 xdg_toplevel.configure（通常不带位置），但此协议扩展需要发送 configure_position。建议在文档中更明确地指出这是对 xdg_shell 行为的补充，确保客户端能区分是配置了大小还是位置。
• set_z_order 中的 hwnd_insert_after 行为：文档指出如果 sibling_id 无效则回退到 hwnd_top。建议补充说明：如果 sibling_id 指向的窗口属于不同的 "Wine session"（不同的 treeland_wine_window_manager_v1 实例），也应视为无效并回退，以增强会话隔离的安全性（虽然 treeland_wine_window_management_unstable-v1.xml 的总述中已提及，但在具体请求描述中再次强调会更清晰）。

2. 代码质量

优点：

• 文档极其详尽：所有的接口、请求、事件、枚举值都附带了详细的 <description>，解释了其用途、参数含义、行为细节以及与 Windows API 的对应关系。这对于实现者和使用者非常有帮助。
• 命名规范：接口和枚举命名采用了清晰的 snake_case，且带有 treeland_wine_ 前缀，避免了命名空间冲突。
• 模块化设计：将窗口几何/堆叠控制 (window_management) 与窗口状态控制 (window_state) 分离为两个独立的协议文件，职责单一，易于维护。
• 引用标准：正确引用了 IETF RFC 2119 来解释 "must", "should" 等关键词。

改进建议：

• 版本管理：协议标记为 unstable-v1。考虑到这是针对特定应用（Wine）的深度定制协议，且涉及到底层窗口管理，变动可能会影响兼容性。建议在文档中增加关于版本升级路径的说明，或者在协议稳定后尽快移除 unstable 前缀。
• window_id 的生命周期：文档提到 window_id 在 "control object" 的生命周期内有效。建议补充说明：如果 xdg_toplevel 被销毁后重新创建（例如同一个 HWND 重新映射），window_id 是否会复用或重新分配。这关系到 Wine 进程间共享内存中 ID 映射表的维护逻辑。
• activate_denied 事件：在 treeland_wine_window_state_v1 中，activate 请求被拒绝时会发送 activate_denied。建议在文档中明确：如果请求被拒绝，合成器是否必须发送此事件？还是仅在特定策略下发送？目前的描述是 "Emitted when the compositor denies..."，这暗示是必须的，这很好，但可以更明确地指出这是客户端判断激活失败（进而可能触发 set_attention）的唯一可靠途径。

3. 代码性能

分析：

• 作为协议定义（XML），本身不涉及运行时性能代码。但其设计直接影响客户端和合成器的实现效率。
• 事件频率：configure_position 可能在窗口拖动时高频触发。由于这是传递绝对坐标，数据量很小（两个 int），性能开销可控。
• 会话边界检查：合成器在处理 set_z_order 时需要验证 sibling_id 是否在同一个 Wine session 中。如果 session 中窗口数量巨大，查找效率可能成为问题。建议在实现侧（非协议定义，但值得注意）使用哈希表（如 std::unordered_map 或 QHash）来维护 window_id 到 window_control 的映射，确保 O(1) 的查找复杂度。

改进建议：

• 批量更新：目前 set_position 和 set_z_order 是分开的请求。如果 Wine 应用频繁调用 SetWindowPos（同时设置位置和 Z 顺序），可能会导致两次往返或两次合成器处理。虽然 Wayland 本身是异步的，但可以考虑是否需要提供一个组合请求（如 set_geometry_and_order）来原子性地处理位置和层级，减少中间状态。不过，考虑到 Windows 消息队列本身也是异步处理的，目前的分开设计也是合理的，主要取决于合成器实现的优化。

4. 代码安全

优点：

• 权限控制意识：文档中多次提到 "The compositor should restrict binding to trusted clients identified by app_id or an equivalent policy mechanism"。这是非常关键的安全设计，防止任意应用滥用这些特权协议（如强制置顶、窃取焦点）。
• 会话隔离：window_id 的作用域限定在 "Wine session" 内，防止跨进程/跨会话的窗口 ID 冲突或恶意操作。
• 输入验证：协议定义了 invalid_sibling 等错误码，要求合成器对参数进行校验。
• 防焦点窃取：treeland_wine_window_state_v1 中的 activate 请求引入了 activate_reason，允许合成器根据来源（用户请求 vs 程序化请求）实施不同的防窃取策略，这是很好的安全实践。

改进建议：

• app_id 验证的强制性：目前文档中说的是 "should restrict binding"（应该限制绑定）。从安全角度出发，建议改为 "must restrict binding"（必须限制绑定），并明确指出：如果客户端不是受信任的 Wine 实例（例如，通过特定的 app-id 如 org.winehq.wine 或白名单机制），合成器必须拒绝绑定该全局接口，并应发送 wl_display.error 或直接断开连接。
• set_attention 的参数验证：timeout_ms 参数是 uint 类型。恶意客户端可能会传入一个极小的值（如 0 或 1）导致合成器或任务栏高频刷新，造成资源耗尽（DoS）。建议在文档中建议合成器实现者对 timeout_ms 设置下限（例如不低于 100ms），即使客户端请求了更快的频率。
• window_id 的随机性：虽然 window_id 仅在 session 内部有效，但为了防止同一 session 内的恶意子进程猜测其他窗口的 ID（如果 session 内部包含不同权限级别的窗口），建议建议合成器实现者分配具有足够熵的 ID，或者至少是单调递增且不可预测的，而不是简单的从 1 开始递增。
• 资源清理：文档要求客户端在销毁 Manager 前销毁所有子对象。建议补充：如果客户端违反此规则，合成器除了报错外，应主动销毁所有相关子对象，防止资源泄漏。

总结

这份协议设计非常专业，充分考虑了 Wine 在 Wayland 上的特殊需求，并在安全性和隔离性上做了周全的考虑。主要的改进点集中在：

1. 修正版权年份。
2. 加强安全相关的约束描述（如将绑定限制改为 "must"）。
3. 细化边界条件和错误处理场景的文档说明。
4. 对实现者提出防御性编程的建议（如参数范围检查、ID 生成策略）。

这些协议文件本身是高质量的，建议的改进主要是为了使其文档更加严谨，并引导合成器实现者编写更安全、更健壮的代码。

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: mogoweb, wineee, zccrs

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• debian/deepin/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment