捕获句柄——屏幕共享时引导协作

考虑一个在某个标签页中运行的 Web 应用，我们将其命名为“main_app”。 假定 main_app 调用 getDisplayMedia， 并且用户选择：

• 共享另一个标签页，其中运行着一个我们称为 “captured_app”的应用。
• 共享一个承载此类标签页的用户代理窗口。

注意：

1. main_app 不知道它正在捕获什么。
2. captured_app 不知道自己正在被捕获，更不用说知道是被谁捕获。

对于一般情况而言，这两个特性都是可取的，但也存在合法的用例， 浏览器会希望允许应用选择加入，以弥合这一差距并 启用连接。

我们希望在保持一般情况与以往相同的同时，启用这些合法用例。

考虑一个协作的演示软件和视频会议软件。假定用户正在一个 VC 会话中。 用户开始共享一个演示文稿。两个应用都希望让 VC 应用发现它正在捕获一个幻灯片会话、 哪个应用，甚至哪个会话，以便 VC 应用能够向用户暴露用于翻阅幻灯片的控件。 当用户点击这些控件时，VC 应用将能够向演示应用发送消息，请求其执行 翻阅幻灯片、进入/离开演示模式等操作。

传输这些消息的手段不在本文档范围内。一些 选项包括：

• 共享的云基础设施。
• 通过 worker 进行消息传递。（注意：存储分区可能会干扰此选项。）
• 可专门为此目的添加一个基本的消息传递 API。

捕获应用通常希望收集有关其用户倾向于捕获哪些应用的统计信息。 例如，VC 应用希望知道其用户共享来自特定提供商的演示应用、 Wikipedia、CNN 等的频率。收集此类信息可用于通过引入新的 协作来改善用户服务，例如上文所描述的协作。

用户有时会选择共享错误的标签页。有时他们会因为误点“改为共享此标签页”按钮， 而切换为共享错误的标签页。一个善意的应用可以在认为用户可能犯错时， 通过显示应用内对话框来要求重新确认，从而尝试保护用户。

此用例是 #3 的一个子用例，但由于其重要性，值得单独成节。 当用户选择共享 VC 通话所在的标签页时，就会出现“镜厅”效应。 在检测到自我捕获时，VC 应用可以避免将被捕获的流再显示给用户， 从而避免这种令人不快的效应。

CaptureHandleConfig 字典用于指示用户代理：被捕获应用打算暴露哪些信息， 以及它愿意向哪些应用暴露上述信息。

WebIDLdictionary CaptureHandleConfig {
  boolean exposeOrigin = false;
  DOMString handle = "";
  sequence<DOMString> permittedOrigins = [];
};

exposeOrigin

如果为 true，用户代理 MUST 通过 CaptureHandle 的 origin 字段暴露被捕获 应用的 origin。如果为 false，用户代理 MUST NOT 暴露被捕获 应用的 origin。

handle

用户代理 MUST 将此值作为 handle 暴露。

注：此字段的值限制为 1024 个 16 位字符。此限制在 setCaptureHandleConfig 中有进一步规定。

permittedOrigins

此字段的有效值包括：

• 空列表。
• 包含单个项目 "*" 的列表。
• 由有效 origin 组成的列表。

如果 permittedOrigins 由单个项目 "*" 组成，则该 CaptureHandle 对所有 捕获者都是可观察的。 否则，CaptureHandle 仅对 其 origin 列在 permittedOrigins 中的捕获者是可观察的。

MediaDevices 扩展了一个方法——setCaptureHandleConfig—— 该方法接受一个 CaptureHandleConfig 对象。通过调用此方法，应用会告知用户代理它允许捕获应用观察哪些信息。

WebIDLpartial interface MediaDevices {
  undefined setCaptureHandleConfig(optional CaptureHandleConfig config = {});
};

setCaptureHandleConfig

用户代理 MUST 运行以下验证：

• 如果 handle 被设置为 无效值，则用户代理 MUST 通过抛出 TypeError 来拒绝。
• 如果 permittedOrigins 被设置为无效值，则用户 代理 MUST 通过抛出 NotSupportedError 来拒绝。
• 如果对 setCaptureHandleConfig() 的调用并非来自顶级 浏览上下文，则用户代理 MUST 通过抛出 InvalidStateError 来拒绝。

如果所有验证都通过，则用户代理 MUST 接受新的 config。 用户代理 MUST 忘记之前对 setCaptureHandleConfig 的任何调用；从现在起， 应用的 CaptureHandleConfig 为 config。

将为所有捕获应用重新评估可观察的 CaptureHandle。

1. 对于每个捕获应用，如果新的可观察的 CaptureHandle 与调用 setCaptureHandleConfig 之前不同，则 用户代理 MUST 触发一个事件，其名称为 capturehandlechange。
2. 每当调用 getCaptureHandle 时，用户代理 MUST 报告新的可观察的 CaptureHandle。

用户代理通过 CaptureHandle 字典， 向捕获应用暴露有关被捕获应用的信息。注意， MUST NOT 将 CaptureHandle 对象 提供给未被允许观察它的捕获应用。

WebIDLdictionary CaptureHandle {
  DOMString origin;
  DOMString handle;
};

origin

如果被捕获应用选择加入以暴露其 origin（通过将 exposeOrigin 设置为 true）， 则用户代理 MUST 将 origin 设置为被捕获 应用的 origin。否则， 不设置 origin。

handle

用户代理 MUST 将此字段设置为被捕获 应用在 handle 中设置的值。

使用名为 getCaptureHandle 的方法扩展 MediaStreamTrack。 当 MediaStreamTrack 是从屏幕捕获派生的视频轨道时， getCaptureHandle 返回最新的 可观察的 CaptureHandle。 否则返回 null。

WebIDLpartial interface MediaStreamTrack {
  CaptureHandle? getCaptureHandle();
};

getCaptureHandle

如果所讨论的轨道不是视频轨道，则用户代理 MUST 返回 null。

如果该轨道不表示 browser 或 window display surface， 则用户 代理 MUST 返回 null。

如果该轨道已结束，则用户 代理 MUST 返回 null。

如果被捕获应用未设置 CaptureHandleConfig，或者如果它最后一次 将其设置为空的 CaptureHandleConfig，则用户 代理 MUST 返回 null。

用户代理 MUST 将捕获 document 的 origin 与被捕获 应用在 permittedOrigins 中列出的那些 origin 进行比较。如果该 捕获 origin 不被允许观察该 CaptureHandle， 则用户代理 MUST 返回 null。

如果之前所有验证均通过，则用户代理 MUST 返回一个 CaptureHandle 字典，其值 派生自被捕获应用最后设置的 CaptureHandleConfig。