Session management
此描述提供了此协议中定义的接口之间交互的高级概述。有关详细信息，请参见协议规范。
xx_session_manager 协议声明了允许客户端从先前执行中恢复 toplevel 状态所必需的接口。xx_session_manager_v1.get_session 请求可用于获取表示一组 toplevel 状态的 xx_session_v1 资源。
客户端可以通过 xx_session_v1.created 事件获取要在未来调用中使用的会话字符串。合成器将此字符串用作未来运行的可识别令牌，可能会在持久存储中存储有关相关 toplevel 的数据。
Toplevel 通过 xx_session_v1.add_toplevel 和 xx_session_toplevel_v1.remove 请求对进行管理。客户端将在 toplevel 映射之前通过 xx_session_v1.restore_toplevel 请求显式请求根据先前状态恢复 toplevel。
警告！此文件中描述的实验性协议可能会进行向后不兼容的主要版本更改。不鼓励在没有 opt-in 机制的情况下公开此协议。
xx_session_manager 接口定义了创建和管理应用程序会话的基本请求。除非显式销毁，否则会话在应用程序和合成器重启之间保持不变。创建会话的目的是在合成器或应用程序重启之间维护应用程序的 xdg_toplevel 表面。合成器应记住给定会话中表面的尽可能多的状态，但不要求必须记住哪些状态。
get_session(id: new_id<xx_session_v1>, reason: uint<xx_session_manager_v1.reason>, session: string)
参数 | 类型 | 描述 |
|---|---|---|
| id | new_id<xx_session_v1> | |
| reason | uint<xx_session_manager_v1.reason> | reason for session |
| session | string允许为空 | the session to restore |
创建与给定会话标识符字符串标识的现有会话或新会话对应的会话对象。当会话对象存在时，会话被视为"正在使用"。
如果标识符字符串表示当前由同一客户端主动使用的会话，则引发 'in_use' 错误。如果其他客户端当前正在使用同一会话，新会话将替换管理关联状态。
传递 NULL 以发起新会话。如果传递的 id 不表示有效会话，合成器将其视为传递了 NULL。
客户端可以同时拥有任意数量的正在使用的会话。
reason { launch, recover, session_restore }
参数 | 值 | 描述 |
|---|---|---|
| launch | 1 | 应用程序是新启动的 应用程序是新启动的 启动了新的应用程序实例，例如从应用程序启动器启动。 |
| recover | 2 | 应用程序已恢复 应用程序已恢复 应用程序实例正在从例如合成器或应用程序崩溃中恢复。 |
| session_restore | 3 | 应用程序已恢复 应用程序已恢复 应用程序实例已恢复，例如作为恢复会话的一部分，或由于资源限制而临时终止后恢复。 |
原因可能决定会话以何种方式恢复关联 toplevel 的窗口管理状态。
例如，新启动的应用程序可能会在活动工作区上以恢复的大小和位置启动，而恢复的应用程序可能会恢复额外的状态，如活动工作区和堆叠顺序。
xx_session_v1
xx_session_v1 对象表示应用程序的会话。当对象存在时，所有已添加到会话的表面将具有合成器存储的状态，可以在以后重新应用。两个会话不能存在于同一标识符字符串中。
添加到会话的表面的状态在更改时由合成器自动更新。
已添加到会话的表面如果调用了 xdg_toplevel.destroy，则会自动从会话中移除。
destroy()
销毁会话对象，保留当前状态但不在状态更改时继续进行进一步更新。这使得关联的 xx_toplevel_session_v1 对象变为惰性。
add_toplevel(id: new_id<xx_toplevel_session_v1>, toplevel: object<xdg_toplevel>, name: string)
参数 | 类型 | 描述 |
|---|---|---|
| id | new_id<xx_toplevel_session_v1> | |
| toplevel | object<xdg_toplevel> | |
| name | string |
尝试将给定表面添加到会话。传递的名称用于标识正在恢复的窗口，并可用于在会话中存储特定于窗口的状态。
使用已被会话管理且具有相同关联的 toplevel 调用此方法将引发 in_use 错误。
restore_toplevel(id: new_id<xx_toplevel_session_v1>, toplevel: object<xdg_toplevel>, name: string)
参数 | 类型 | 描述 |
|---|---|---|
| id | new_id<xx_toplevel_session_v1> | |
| toplevel | object<xdg_toplevel> | |
| name | string |
通知合成器与传递的名称关联的 toplevel 应恢复其窗口管理状态。
使用已被会话管理且具有相同关联的 toplevel 调用此方法将引发 in_use 错误。
此请求必须在关联的 wl_surface 的第一次提交之前调用，否则将引发 already_mapped 错误。
作为初始 configure 序列的一部分，如果 toplevel 成功恢复，将发出 xx_toplevel_session_v1.restored 事件。有关详细信息，请参见 xx_toplevel_session_v1.restored 事件。
created(id: string)
参数 | 类型 | 描述 |
|---|---|---|
| id | string |
在获取新会话对象后的某个时间最多发出一次。这意味着未恢复先前状态，并且创建了新会话。传递的 id 可用于恢复先前的会话。
error { invalid_restore, name_in_use, already_mapped }
参数 | 值 | 描述 |
|---|---|---|
| invalid_restore | 1 | 初始 toplevel 提交后无法执行恢复 |
| name_in_use | 2 | toplevel 名称已被使用 |
| already_mapped | 3 | 恢复时 toplevel 已映射 |
remove()
从会话中移除指定表面，并使任何对应的 xx_toplevel_session_v1 对象变为惰性。合成器应从其内部存储中删除相应会话中与 toplevel 相关的任何数据。
restored(surface: object<xdg_toplevel>)
参数 | 类型 | 描述 |
|---|---|---|
| surface | object<xdg_toplevel> |
"restored" 事件在 toplevel 的第一次 xdg_toplevel.configure 之前发出。它只会在 xx_session_v1.restore_toplevel 之后以及初始空表面状态已应用后发出，它表示表面的会话正在通过此 configure 事件恢复。
合成器支持
Copyright
Copyright 2018 Mike Blumenkrantz Copyright 2018 Samsung Electronics Co., Ltd Copyright 2018 Red Hat Inc.
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 (including the next paragraph) 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.