feat: add prelaunch splash screen protocol v2

[wineee]

Added new Wayland protocol treeland-prelaunch-splash-v2.xml to support enhanced prelaunch splash screen functionality. This version introduces a splash object that allows bidirectional communication between the compositor and applications. Key improvements include proper object lifecycle management where callers can destroy splash objects to dismiss them, and compositors can send events like timeouts back to callers. The protocol also adds support for instance IDs to handle multiple application instances and requires sandbox engine names for security context identification.

Log: Added new prelaunch splash screen protocol with enhanced object management and bidirectional communication

Influence:

1. Test splash screen creation with valid app_id, instance_id, and sandbox_engine_name
2. Verify splash object destruction properly dismisses the splash screen
3. Test compositor events like timeout notifications through the splash object
4. Validate multiple splash instances for non-singleton applications
5. Check XWayland window matching with splash screens
6. Test optional icon buffer functionality with null and valid buffers

feat: 添加预启动闪屏协议 v2 版本

新增 Wayland 协议 treeland-prelaunch-splash-v2.xml 以支持增强的预启动闪 屏功能。此版本引入了闪屏对象，支持合成器和应用程序之间的双向通信。主要改
进包括正确的对象生命周期管理，调用者可以销毁闪屏对象来关闭闪屏，合成器可
以通过对象发送超时等事件给调用者。协议还增加了实例 ID 支持以处理多个应用
程序实例，并要求沙盒引擎名称用于安全上下文识别。

Log: 新增预启动闪屏协议，支持增强的对象管理和双向通信

Influence:

1. 测试使用有效的 app_id、instance_id 和 sandbox_engine_name 创建闪屏
2. 验证销毁闪屏对象是否正确关闭闪屏
3. 测试合成器通过闪屏对象发送的超时等事件通知
4. 验证非单例应用程序的多个闪屏实例
5. 检查 XWayland 窗口与闪屏的匹配机制
6. 测试可选图标缓冲区功能，包括空值和有效缓冲区

[deepin-ci-robot]

deepin pr auto review

这份代码审查针对新增的 Wayland 协议扩展 treeland-prelaunch-splash-v2 及其 CMake 构建配置修改。总体来看，协议定义清晰，改进了 v1 版本的交互模式（从单向通知改为双向对象交互），但存在一些潜在的逻辑、安全和规范性问题。

以下是详细的审查意见：

1. 语法与规范性

• 版权年份错误：
  • 问题：xml/treeland-prelaunch-splash-v2.xml 中的版权年份写为 2026。
  • 建议：通常应填写当前年份或代码创建时的实际年份。除非这是未来发布的预留代码，否则应修正为当前年份（如 2023 或 2024）。
• 协议命名一致性：
  • 观察：接口名称 treeland_prelaunch_splash_manager_v2 和 treeland_prelaunch_splash_v2 均带有 _v2 后缀，且文件名为 v2.xml，这是很好的做法，有助于与 v1 版本区分。
• CMakeLists 修改：
  • 观察：在 XML 列表中正确添加了新文件，符合构建系统规范。

2. 代码逻辑与功能

• 缺少超时事件定义：
  • 问题：在 treeland_prelaunch_splash_manager_v2 的描述中提到："the compositor can send events (e.g. timeout) back to the caller through the object"。然而，在 treeland_prelaunch_splash_v2 接口的定义中，并没有定义任何事件。
  • 建议：必须在 treeland_prelaunch_splash_v2 接口中添加相应的事件定义。例如：

    <event name="timeout">
        <description summary="the splash was closed due to a timeout">
            The compositor closed the splash screen because the application
            window did not appear within the expected time frame.
            The splash object is invalid after this event.
        </description>
    </event>

• 对象生命周期管理：
  • 问题：描述中提到 "The caller can destroy the object to dismiss the splash"。这明确指出了客户端主动销毁的语义。
  • 建议：需要明确当 compositor 发送事件（如上述的 timeout）后，该 wl_object 是否仍然有效。通常协议会规定服务端在发送特定事件后隐式销毁对象，或者要求客户端必须调用 destroy。建议在文档中明确这一点，或者在事件中添加 since 版本号说明。

3. 代码安全

• 参数验证与空指针风险：
  • 问题：create_splash 请求中，sandbox_engine_name 被标记为 required, non-empty，但 app_id 和 instance_id 仅标记为 string。
  • 建议：
    • 如果 app_id 对于匹配窗口至关重要，建议在文档中明确其是否允许为空字符串。通常 app_id 不应为空。
    • 对于 icon_buffer，使用了 allow-null="true"，这是合理的，但实现方需注意处理 NULL 指针的情况，避免解引用崩溃。
• 资源泄漏风险：
  • 问题：icon_buffer 参数传入了一个 wl_buffer。如果客户端传入了一个 buffer 但随后立即销毁了 splash 对象，或者 compositor 持有该 buffer 的引用但未正确释放，可能导致内存泄漏或悬空指针。
  • 建议：在文档中补充说明 compositor 对 icon_buffer 的引用生命周期。例如："The compositor may take a reference to the buffer..." 或 "The client must not destroy the buffer until..."。

4. 代码性能

• 缓冲区传递机制：
  • 观察：使用 wl_buffer 传递图标数据。
  • 建议：这是一个标准做法，性能较好。但考虑到这是启动画面，通常图标较小。如果图标数据量不大，可以考虑是否支持通过文件描述符（FD）传递图片数据路径，由 compositor 自行加载（但这会增加 compositor 的解码负担）。目前的 wl_buffer 方案是合理的，将解码压力留给了客户端。

总结与修改建议代码

建议对 xml/treeland-prelaunch-splash-v2.xml 进行如下修改，主要是修正版权年份并补充缺失的事件定义：

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="treeland_prelaunch_splash_v2">

    <copyright><![CDATA[
    SPDX-FileCopyrightText: 2024 UnionTech Software Technology Co., Ltd.
    SPDX-License-Identifier: MIT
    ]]></copyright>

    <interface name="treeland_prelaunch_splash_manager_v2" version="1">
        <description summary="prelaunch splash screen manager">
            This interface is a manager for creating prelaunch splash screens.
            <!-- ... (描述保持不变) ... -->
        </description>

        <request name="destroy" type="destructor">
            <description summary="destroy the manager"/>
        </request>

        <request name="create_splash">
            <description summary="create a new splash screen">
                Creates a new prelaunch splash screen and returns a splash object.

                The `app_id` is a string that identifies the application. The compositor
                will use this ID together with `sandbox_engine_name` to match the splash
                screen with the actual application window when it appears. This
                matching mechanism should also work for XWayland windows.

                The `instance_id` identifies a specific application instance, allowing
                multiple splashes for non-singleton applications. The compositor can
                use this to associate a splash with a particular launch instance.

                Callers MUST provide a non-empty `sandbox_engine_name` string which
                identifies the sandboxing/container.
            </description>
            <arg name="splash" type="new_id" interface="treeland_prelaunch_splash_v2" summary="new splash object"/>
            <arg name="app_id" type="string" summary="the application ID (required, non-empty)"/>
            <arg name="instance_id" type="string" summary="the application instance ID"/>
            <arg name="sandbox_engine_name" type="string" summary="the sandbox engine / security context name (required, non-empty)"/>
            <arg name="icon_buffer" type="object" interface="wl_buffer" allow-null="true" summary="optional icon image as wl_buffer (e.g. wl_shm)"/>
        </request>
    </interface>

    <interface name="treeland_prelaunch_splash_v2" version="1">
        <description summary="prelaunch splash screen object">
            Represents a single prelaunch splash screen created by the manager.

            The caller can destroy this object to dismiss the corresponding splash.
            The compositor may also send events through this object, for example
            to notify the caller that the splash was closed due to a timeout.
            
            After the 'timeout' event is sent, this object is inert and the client
            should destroy it.
        </description>

        <!-- 新增：超时事件 -->
        <event name="timeout">
            <description summary="the splash was closed due to a timeout">
                The splash screen was closed by the compositor because the
                application window did not appear within the expected time frame.
                The client should destroy this object upon receiving this event.
            </description>
        </event>

        <request name="destroy" type="destructor">
            <description summary="dismiss and destroy the splash">
                Dismisses the splash screen and destroys this object.
            </description>
        </request>
    </interface>
</protocol>

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: 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