4.4.2 接口定义

4.4.2 接口定义

本节中介绍的 RTCPeerConnection 接口通过本规范中的几个部分接口进行了扩展。值得注意的是，RTP Media API部分添加了 API 以发送和接收 MediaStreamTrack 对象。

[Constructor(optional RTCConfiguration configuration),
  Exposed=Window]
interface RTCPeerConnection : EventTarget {
  Promise<RTCSessionDescriptionInit> createOffer(optional RTCOfferOptions options);
  Promise<RTCSessionDescriptionInit> createAnswer(optional RTCAnswerOptions options);
  Promise<void> setLocalDescription(RTCSessionDescriptionInit description);
  readonly attribute RTCSessionDescription? localDescription;
  readonly attribute RTCSessionDescription? currentLocalDescription;
  readonly attribute RTCSessionDescription? pendingLocalDescription;
  Promise<void> setRemoteDescription(RTCSessionDescriptionInit description);
  readonly attribute RTCSessionDescription? remoteDescription;
  readonly attribute RTCSessionDescription? currentRemoteDescription;
  readonly attribute RTCSessionDescription? pendingRemoteDescription;
  Promise<void> addIceCandidate(RTCIceCandidateInit candidate);
  readonly attribute RTCSignalingState signalingState;
  readonly attribute RTCIceGatheringState iceGatheringState;
  readonly attribute RTCIceConnectionState iceConnectionState;
  readonly attribute RTCPeerConnectionState connectionState;
  readonly attribute boolean? canTrickleIceCandidates;
  static sequence<RTCIceServer> getDefaultIceServers();
  RTCConfiguration getConfiguration();
  void setConfiguration(RTCConfiguration configuration);
  void close();
  attribute EventHandler onnegotiationneeded;
  attribute EventHandler onicecandidate;
  attribute EventHandler onicecandidateerror;
  attribute EventHandler onsignalingstatechange;
  attribute EventHandler oniceconnectionstatechange;
  attribute EventHandler onicegatheringstatechange;
  attribute EventHandler onconnectionstatechange;
};

构造函数

RTCPeerConnection

请参阅 RTCPeerConnection 构造函数算法。

属性

localDescription类型 RTCSessionDescription，只读，不能为空：

如果 localDescription 属性不为 null，则它必须返回[[PendingLocalDescription]]，否则它必须返回[[CurrentLocalDescription]]。

注意[[CurrentLocalDescription]].sdp和[[PendingLocalDescription]].sdp不需要与传递给相应 setLocalDescription 调用的 SDP 值完全相同（即 SDP 可以被解析和重新格式化，并且可以添加 ICE 候选者） 。

currentLocalDescription类型为 RTCSessionDescription，只读，不能为空：

currentLocalDescription 属性必须返回[[CurrentLocalDescription]]。

它表示上次 RTCPeerConnection 转换为稳定状态时成功协商的本地描述，以及自创建 offer 或 answer 以来 ICE 代理生成的任何本地候选项。

pendingLocalDescription类型为 RTCSessionDescription，只读，不能为空：

pendingLocalDescription 属性必须返回[[PendingLocalDescription]]。

它表示正在协商的本地描述以及自创建 offer 或 answer 以来 ICE 代理生成的任何本地候选人。如果 RTCPeerConnection 处于稳定状态，则该值为空。

remoteDescription类型 RTCSessionDescription，只读，不能为空：

remoteDescription 属性必须返回[[PendingRemoteDescription]]，如果它不为 null，否则它必须返回[[CurrentRemoteDescription]]。

注意[[CurrentRemoteDescription]].sdp和[[PendingRemoteDescription]].sdp 不需要与传递给相应的 setRemoteDescription 调用的 SDP 值完全相同（即 SDP 可以被解析和重新格式化，并且可以添加 ICE 候选者） 。

currentRemoteDescription类型为RTCSessionDescription，只读，不能为空：

currentRemoteDescription 属性必须返回[[CurrentRemoteDescription]]。

它表示上次 RTCPeerConnection 转换为稳定状态时成功协商的最后一个远程描述，以及自创建 offer 或 answer 以来通过addIceCandidate（）提供的任何远程候选。

pendingRemoteDescription类型RTCSessionDescription，只读，不能为空：

pendingRemoteDescription 属性必须返回[[PendingRemoteDescription]]。

它表示正在协商过程中的远程描述，包括自创建 offer 或 answer 以来通过 addIceCandidate（）提供的任何远程候选项。如果 RTCPeerConnection 处于稳定状态，则该值为空。

TRANSPCS 类型为 RTCSignalingState 的 signalingState， 只读:

signalingState 属性必须返回 RTCPeerConnection 对象的信令状态。

iceGatheringState类型为RTCIceGatheringState，只读

iceGatheringState 属性必须返回 RTCPeerConnection 实例的 ICE 收集状态。

RTCIceConnectionState类型的iceConnectionState，只读

iceConnectionState 属性必须返回 RTCPeerConnection 实例的 ICE 连接状态。

类型为RTCPeerConnectionState的connectionState，只读：

connectionState 属性必须返回 RTCPeerConnection 实例的连接状态。

canTrickleIceCandidates类型为boolean，只读，不能为空：

The canTrickleIceCandidates attribute indicates whether the remote peer is able to accept trickled ICE candidates [TRICKLE-ICE]. The value is determined based on whether a remote description indicates support for trickle ICE, as defined in [JSEP] (section 4.1.15.). Prior to the completion of setRemoteDescription, this value is null.

canTrickleIceCandidates 属性指示远程对等方是否能够接受 trickle ICE 候选[TRICKLE-ICE]。该值是根据远程描述是否表示支持 trickle ICE 确定的，如[JSEP]（第4.1.15节）中所定义。在完成 setRemoteDescription 之前，此值为 null。

onnegotiationneeded 类型 EventHandler

此事件处理程序的事件类型是 negotiationneeded。

eventHandler 类型的 onicecandidate

此事件处理程序的事件类型是 icecandidate。

eventHandler 类型的 onicecandidateerror

此事件处理程序的事件类型是 icecandidateerror。

onSignalingstate 类型 EventHandler 的更改

此事件处理程序的事件类型是 signalingstatechange。

eventHandler 类型的 oniceconnectionstatechange

此事件处理程序的事件类型是 iceconnectionstatechange

eventHandler 类型的 onicegatheringstatechange

此事件处理程序的事件类型是 icegatheringstatechange。

eventHandler 类型的 onconnectionstatechange

此事件处理程序的事件类型是 connectionstatechange。

方法

createOffer

createOffer 方法生成一个 SDP blob，其中包含 RFC 3264 offer，其中包含会话支持的配置，包括附加到此 RTCPeerConnection 的本地 MediaStreamTracks 的说明，此实现支持的编解码器/ RTP / RTCP 功能以及 ICE 的参数代理和 DTLS 连接。可以提供选项参数以提供对所生成的 offer 的额外控制。

如果系统具有有限的资源（例如，有限数量的解码器），则 createOffer 需要返回反映系统当前状态的 offer，以便 setLocalDescription 在尝试获取这些资源时成功。会话描述必须仍然可以通过 setLocalDescription 保持可用，而不会导致错误，直到至少返回的 promise 的履行回调结束。

创建 SDP 必须遵循适当的流程来生成[JSEP]中描述的 offer。作为要约，生成的 SDP 将包含会话支持或优选的全套编解码器/ RTP / RTCP功能（而不是 answer，其将仅包括要使用的特定协商子集）。如果在建立会话后调用 createOffer，createOffer 将生成与当前会话兼容的 offer，其中包含自上次完成 offer - 应答交换以来对会话所做的任何更改，例如添加或删除轨道。如果未进行任何更改，则要约将包括当前本地描述的功能以及可在更新的要约中协商的任何其他功能。

生成 SDP还将包含 ICE 代理的 usernameFragment，密码和 ICE 选项（在[ICE]，第14节中定义），还可以包含代理收集的任何本地候选。

RTCPeerConnection 的配置中的证书值提供了应用程序为 RTCPeerConnection 配置的证书。这些证书以及任何默认证书用于生成一组证书指纹。这些证书指纹用于构建 SDP 和作为身份断言请求的输入。

如果 RTCPeerConnection 配置为通过调用 setIdentityProvider 生成 Identity 断言，则会话描述应包含适当的断言。

生成 SDP 的过程暴露了底层系统的媒体功能的子集，其在设备上提供通常持久的跨源信息。因此，它增加了应用的指纹表面。在隐私敏感的上下文中，浏览器可以考虑缓解，例如仅生成 SDP 匹配功能的公共子集。

调用该方法时，用户代理必须执行以下步骤：

让connection 成为调用方法的 RTCPeerConnection 对象。

如果connection的[[IsClosed]] 值为 true，则返回使用新创建的 InvalidStateError 拒绝的 promise。

如果使用身份提供程序配置连接，则在尚未开始的情况下开始身份声明请求过程。

将以下步骤的结果返回到连接的操作队列：

让p成为新的Promise。

同时，在给定 p 的情况下，开始创建 offer 的步骤。

返回p。

在给定承诺 p 的情况下创建要约的步骤如下：

如果未使用一组证书构建连接，并且尚未生成一个证书，请等待生成。

如果已配置提供者，则提供者是连接的当前配置身份提供者，否则为 null。

如果 provider 为非 null，则等待身份断言请求过程完成。

如果提供程序无法生成标识声明，请使用新创建的 NotReadableError 拒绝 p 并中止这些步骤。

检查系统状态以确定生成要约所需的当前可用资源，如[JSEP]（第4.1.6节）中所述。

如果此检查因任何原因失败，请使用新创建的 OperationError 拒绝p并中止这些步骤。

在给定 p 的情况下，对运行最终步骤以创建 offer 的任务进行排队。

给出承诺 p 创建要约的最后步骤如下：

如果connection的[[IsClosed]] 值为true，则中止这些步骤。

如果以这样的方式修改连接，即需要对系统状态进行额外检查，或者如果其配置的 indentity 提供程序不再是提供者，则并行开始执行再次创建 offer 的步骤，给定 p，并中止这些步骤。

NOTE：如果仅在连接中添加了音频RTCRtpTransceiver时调用了createOffer，但在执行并行创建 offer的步骤时，可能需要添加视频RTCRtpTransceiver，这需要额外检查视频系统资源。

给定从先前检查获得的信息，当前连接状态及其 RTCRtpTransceivers，以及来自提供者的身份断言（如果非空），生成 SDP offer sdpString，如[JSEP]（第5.2节）中所述。

如[捆绑]（第7节）中所述，如果使用捆绑（请参阅RTCBundlePolicy），则必须选择标记为 m = section 的提议者才能协商 BUNDLE 组。用户代理必须选择 m = 部分，该部分对应于收发器集合中的第一个不停止的收发器，作为提供者标记的 m = 部分。这允许远程端点预测哪个收发器是提供者标记的 m = 部分而不必解析 SDP。

m = 段的相关收发器的编解码器首选项被称为 RTCRtpTranceiver 的[[PreferredCodecs]]的值，应用了以下过滤（或者如果[[PreferredCodecs]]为空则表示不设置）：

如果方向是“sendrecv”，则排除 RTCRtpSender.getCapabilities（kind）.codecs 和 RTCRtpReceiver.getCapabilities（kind）.codecs 交集中未包含的任何编解码器。

如果方向是“sendonly”，则排除 RTCRtpSender.getCapabilities（kind）.codecs 中未包含的任何编解码器。

如果方向是“recvonly”，则排除 RTCRtpReceiver.getCapabilities（kind）.codecs 中未包含的任何编解码器。

过滤绝不能改变编解码器首选项的顺序。

让 offer 成为一个新创建的 RTCSessionDescriptionInit 字典，其类型成员初始化为字符串“offer”，其 sdp 成员初始化为 sdpString。

将[[LastOffer]]内部值设置为 sdpString。

用 Resolve 解决 p。

createAnswer

createAnswer 方法使用支持的会话配置生成[SDP] answer，该配置与远程配置中的参数兼容。与 createOffer 一样，返回的 SDP blob 包含附加到此 RTCPeerConnection 的本地 MediaStreamTracks 的描述，为此会话协商的编解码器/ RTP / RTCP 选项，以及 ICE 代理收集的任何候选项。可以提供选项参数以提供对生成的 answer 的附加控制。

与 createOffer 一样，返回的描述应该反映系统的当前状态。会话描述必须仍然可以通过 setLocalDescription 保持可用，而不会导致错误，直到至少返回的 promise 的履行回调结束。

作为 answer，生成的SDP将包含特定的编解码器/ RTP / RTCP 配置，该配置与相应的 offer 一起指定应如何建立媒体平面。 SDP 的生成必须遵循生成[JSEP]中描述的 answer 的适当过程。

生成的 SDP 还将包含 ICE 代理的 usernameFragment，密码和 ICE 选项（在[ICE]，第14节中定义），还可以包含代理收集的任何本地候选。

RTCPeerConnection 的配置中的证书值提供了应用程序为 RTCPeerConnection 配置的证书。这些证书以及任何默认证书用于生成一组证书指纹。这些证书指纹用于构建 SDP 和作为身份断言请求的输入。

通过将类型设置为“pranswer”，可以将 answer 标记为临时，如[JSEP]（第4.1.8.1节）中所述。

如果RTCPeerConnection配置为通过调用 setIdentityProvider 生成 Identity 断言，则会话描述应包含适当的断言。

调用该方法时，用户代理必须执行以下步骤：

让 connection 成为调用方法的 RTCPeerConnection 对象。

如果connection的[[IsClosed]]值为 true，则返回使用新创建的 InvalidStateError 拒绝的 promise。

如果使用身份提供程序配置连接，则在尚未开始的情况下开始身份声明请求过程。

将以下步骤的结果返回到连接的操作队列：

如果连接的信令状态既不是“have-remote-offer”也不是“have-local-pranswer”，则返回使用新创建的 InvalidStateError 拒绝的 promise。

让 p 成为新的 Promise。

同时，在给定 p 的情况下，开始创建 answer 的步骤。

返回p。

给出 p 创建 answer 的步骤如下：

如果未使用一组证书构建连接，并且尚未生成一个证书，请等待生成。

如果已配置提供者，则提供者是连接的当前配置身份提供者，否则为 null。

如果 provider 为非 null，则等待身份断言请求过程完成。

如果提供程序无法生成标识声明，请使用新创建的 NotReadableError 拒绝 p 并中止这些步骤。

检查系统状态以确定生成 answer 所需的当前可用资源，如[JSEP]（第4.1.7节）中所述。

如果此检查因任何原因失败，请使用新创建的 OperationError 拒绝 p 并中止这些步骤。

在给定 p 的情况下，对运行最终步骤以创建 answer 的任务进行排队。

给出承诺 p 创建 answer 的最后步骤如下：

如果connection的[[IsClosed]] 值为 true，则中止这些步骤。

如果以这样的方式修改连接，即需要对系统状态进行额外检查，或者如果其配置的 indentity 提供程序不再是提供者，那么并行开始步骤再次创建 answer，给定 p，并中止这些步骤。

NOTE：如果在 RTCRtpTransceiver 的方向是“recvonly”时调用 createAnswer，则可能需要这样做，但在执行并行创建  answer 的步骤时，方向已更改为“sendrecv”，需要额外检查视频编码资源。
给定从先前检查获得的信息以及当前连接状态及其 RTCRtpTransceivers，以及来自提供者的身份断言（如果非空），生成 SDP answersdpString，如[JSEP]（第5.3节）中所述。 。
m =段的相关收发器的编解码器首选项被称为 RTCRtpTranceiver的[[PreferredCodecs]]的值，应用了以下过滤（或者如果[[PreferredCodecs]]为空则表示不设置）：

如果方向是“sendrecv”，则排除 RTCRtpSender.getCapabilities（kind）.codecs 和 RTCRtpReceiver.getCapabilities（kind）.codecs交集中未包含的任何编解码器。

如果方向是“sendonly”，则排除 RTCRtpSender.getCapabilities（kind）.codecs 中未包含的任何编解码器。

如果方向是“recvonly”，则排除 RTCRtpReceiver.getCapabilities（kind）.codecs 中未包含的任何编解码器。

过滤绝不能改变编解码器首选项的顺序。

让我们回答一个新创建的 RTCSessionDescriptionInit 字典，其类型成员初始化为字符串“answer”，其 sdp 成员初始化为 sdpString。

将[[LastAnswer]]值设置为sdpString。

Resolve p 并返回answer。

setLocalDescription

setLocalDescription 方法指示 RTCPeerConnection 将提供的 RTCSessionDescriptionInit 应用为本地描述。

此 API 更改本地媒体状态。为了成功处理应用程序想要提供的从一种媒体格式更改为不同的不兼容格式的场景，RTCPeerConnection 必须能够同时支持使用当前和未决的本地描述（例如，支持两者中存在的编解码器）描述）直到收到最终 answer，此时 RTCPeerConnection 可以完全采用待处理的本地描述，或者如果远程端拒绝更改，则回滚到当前描述。

如[JSEP]（第5.4节）中所述，从 createOffer 或 createAnswer 返回的 SDP 在传递给 setLocalDescription 之前不得更改。因此，当调用该方法时，用户代理必须运行以下步骤：

让 description 成为 setLocalDescription 的第一个参数。

如果 description.sdp 为空字符串且 description.type 为“answer” 或 “pranswer”，则将 description.sdp 设置为connection [[LastAnswer]]的值。

如果 description.sdp 为空字符串且 description.type 为 “offer”，则将 description.sdp 设置为 connection [[LastOffer]]的值。

返回设置描述所指示的 RTCSessionDescription 的结果。

如[JSEP]（第5.9节）所述，调用此方法可能会触发 ICE 代理的 ICE 候选人收集过程。

setRemoteDescription

setRemoteDescription 方法指示 RTCPeerConnection 将提供的 RTCSessionDescriptionInit 应用为远程提供或 answer。此 API 更改本地媒体状态。

调用该方法时，用户代理必须返回设置方法的第一个参数指示的 RTCSessionDescription 的结果。

此外，处理远程描述以确定和验证对等体的身份。

如果会话描述中存在 a = identity 属性，则浏览器验证标识声明。

如果 peerIdentity 配置应用于 RTCPeerConnection，则会建立所提供值的目标对等体标识。或者，如果 RTCPeerConnection 先前已经验证了对等体的身份（即，解析了peerIdentity promise），那么这也建立了目标对等体身份。

设置后，目标对等身份不能更改。

如果设置了目标对等体标识，则必须在声明返回 setRemoteDescription 解析之前完成身份验证。如果身份验证失败，则会拒绝 setRemoteDescription 返回的承诺。

如果没有目标对等体标识，则 setRemoteDescription 不会等待完成身份验证。

addIceCandidate

addIceCandidate 方法为 ICE 代理提供远程候选。当用候选成员的空字符串调用时，此方法还可用于指示远程候选者的结束。此方法使用的参数的唯一成员是 candidate，sdpMid，sdpMLineIndex 和 usernameFragment;其余的都被忽略了。调用该方法时，用户代理必须运行以下步骤：

让候选人成为方法的参数。

让 connection 成为调用方法的 RTCPeerConnection 对象。

如果 candidate.candidate 不是空字符串且 candidate.sdpMid 和 candidate.sdpMLineIndex 都为 null，则返回使用新创建的 TypeError拒绝的 promise。

将以下步骤的结果返回到连接的操作队列：

如果 remoteDescription 为 null，则返回使用新创建的 InvalidStateError 拒绝的承诺。

让p成为新的Promise。

如果candidate.sdpMid不为null，请运行以下步骤：

如果 candidate.sdpMid 不等于 remoteDescription 中任何媒体描述的中间部分，则使用新创建的 OperationError拒绝 p 并中止这些步骤。

否则，如果candidate.sdpMLineIndex不为null，请运行以下步骤：

如果 candidate.sdpMLineIndex 等于或大于 remoteDescription 中的媒体描述数，则使用新创建的 OperationError 拒绝 p 并中止这些步骤。

如果 candidate.usernameFragment 既不是未定义也不是 null，并且不等于应用的远程描述的相应媒体描述中存在的任何用户名片段，则使用新创建的 OperationError 拒绝 p 并中止这些步骤。

如果 candidate.usernameFragment 既不是未定义也不是 null，并且不等于应用的远程描述的相应媒体描述中存在的任何用户名片段，则使用新创建的 OperationError 拒绝p并中止这些步骤。

同时，按照[JSEP]（第4.1.17节）中的描述添加 ICE 候选候选者。使用 candidate.usernameFragment 来标识 ICE 生成;如果 usernameFragment 为 null，则处理最近 ICE 生成的候选项。如果 candidate.candidate 是空字符串，则将候选处理作为对应的媒体描述和 ICE 候选生成的候选结束指示。如果 candidate.sdpMid 和 candidate.sdpMLineIndex 都为 null，则这适用于所有媒体描述。

    zh:如果无法成功添加候选者，则用户代理必须对运行以下步骤的任务进行排队：

如果 connection的[[IsClosed]] 的值为true，则中止这些步骤。

使用新创建的 OperationError 拒绝 p 并中止这些步骤。

    zh:如果候选成功应用，则用户代理必须对运行以下步骤的任务进行排队：

如果 connection的[[IsClosed]] 的值为 true，则中止这些步骤。

如果 connection.[[PendingRemoteDescription]] 不为 null，并且表示处理候选的 ICE 生成，则将候选添加到连接.[[PendingRemoteDescription]].sdp。

如果 connection.[[CurrentRemoteDescription]]不为 null，并且表示处理候选的 ICE 生成，则将候选添加到connection.[[CurrentRemoteDescription]].sdp。

Resolve p 并返回 undefined。

返回p。

NOTE:由于 WebIDL 处理，addIceCandidate（null） 被解释为具有默认字典的调用，在上述算法中，该字典指示所有媒体描述和 ICE 候选生成的候选结束。这是出于遗留原因的设计。

getDefaultIceServers

返回配置到浏览器中的 ICE 服务器列表。浏览器可能配置为使用本地或私有 STUN 或 TURN 服务器。此方法允许应用程序了解这些服务器并可选择使用它们。

此列表可能是持久的，并且在起源之间是相同的。因此，它增加了浏览器的指纹表面。在隐私敏感的上下文中，浏览器可以考虑缓解，例如仅将此数据提供给白名单来源（或根本不提供）。

NOTE:由于此信息的使用由应用程序开发人员自行决定，因此使用这些默认值配置用户代理本身并不会增加用户限制其 IP 地址暴露的能力。

getConfiguration

返回表示此 RTCPeerConnection 对象的当前配置的 RTCConfiguration 对象。

调用此方法时，用户代理必须返回存储在[[Configuration]]内部值中的 RTCConfiguration 对象。

setConfiguration

setConfiguration 方法更新此 RTCPeerConnection 对象的配置。这包括更改 ICE 代理的配置。如[JSEP]（第3.5.1节）中所述，当 ICE 配置以需要新收集阶段的方式更改时，需要重新启动 ICE。

调用 setConfiguration 方法时，用户代理必须运行以下步骤：

让 connection 成为调用方法的 RTCPeerConnection。

如果 connection的[[IsClosed]]的值为 true，则抛出 InvalidStateError。

设置配置指定的配置。

close

当调用 close 方法时，用户代理必须运行以下步骤：

让 connection 成为调用方法的 RTCPeerConnection 对象。

如果 connection的[[IsClosed]]的值为 true，则中止这些步骤。

将connection.[[IsClosed]]插槽设置为 true。

将连接的信令状态设置为“closed”。

让收发器成为执行 CollectTransceivers 算法的结果。对于收发器中的每个 RTCRtpTransceiver 收发器，请运行以下步骤：

如果收发器的[[Stoped]]的值为真，则中止这些步骤。

让发送者成为收发器的[[Sender]]。

让接收器成为收发器的[[Receiver]]。

停止向发件人发送媒体。

按照[RFC3550]中的规定，为发送方发送的每个 RTP 流发送 RTCP BYE。

停止使用接收器接收媒体。

将接收者的[[ReceiverTrack]]的readyState设置为“ends”。

将收发器的[[Stopped]]的值设置为 true。

将每个连接的RTCDataChannels的[[ReadyState]]的值设置为“closed”。

RTCDataChannels将突然关闭，并且不会调用关闭过程。

如果connection.[[SctpTransport]] 不为 null，则通过发送 SCTP ABORT 块并将[[SctpTransportState]]设置为“closed”来拆除底层 SCTP 关联。

将每个连接的 RTCDtlsTransports.[[DtlsTransportState]]的值设置为“closed”。

销毁连接的 ICE 代理，突然结束任何活动的 ICE 处理并释放任何相关资源（例如 TURN 权限）。

将每个连接的 RTCIceTransports 的[[IceTransportState]]插槽设置为“closed”。

将连接的 ICE 连接状态设置为“closed”。

将连接的连接状态设置为“closed”。