RTCPeerConnection

基线 广泛可用

此功能已发展成熟,并在许多设备和浏览器版本中运行良好。它自 2020 年 1 月.

构造函数

RTCPeerConnection()

RTCPeerConnection 接口表示本地计算机和远程对等体之间的 WebRTC 连接。它提供用于连接到远程对等体、维护和监控连接以及在不再需要时关闭连接的方法。

实例属性

返回一个新的 RTCPeerConnection,表示本地设备和远程对等体之间的连接。

也继承了 EventTarget 的属性。

canTrickleIceCandidates 只读

返回一个布尔值,指示远程对等体是否可以接受 trickled ICE 候选

connectionState 只读

通过返回以下字符串之一来指示对等连接的当前状态:newconnectingconnecteddisconnectedfailedclosed

currentLocalDescription 只读

返回一个 RTCSessionDescription 对象,描述自上次此 RTCPeerConnection 完成协商和连接到远程对等体以来最后一次成功协商的连接的本地端。还包括 ICE 代理可能已在此描述所代表的要约或应答首次实例化后生成的任何 ICE 候选列表。

currentRemoteDescription 只读

返回一个 RTCSessionDescription 对象,描述自上次此 RTCPeerConnection 完成协商和连接到远程对等体以来最后一次成功协商的连接的远程端。还包括 ICE 代理可能已在此描述所代表的要约或应答首次实例化后生成的任何 ICE 候选列表。

iceConnectionState 只读

返回一个字符串,描述与此 RTCPeerConnection 关联的 ICE 代理的状态。它可以是以下值之一:newcheckingconnectedcompletedfaileddisconnectedclosed

iceGatheringState 只读

返回一个字符串,描述连接的 ICE 收集状态。这使您可以检测例如 ICE 候选收集何时完成。可能的值是:newgatheringcomplete

localDescription 只读

返回一个 RTCSessionDescription,描述连接的本地端会话。如果尚未设置,则返回 null

peerIdentity 只读

返回一个 Promise,它解析为一个 RTCIdentityAssertion,其中包含标识远程对等体的字符串。一旦此 promise 成功解析,结果标识就是目标对等体标识,并且在连接持续期间不会更改。

pendingLocalDescription 只读

返回一个 RTCSessionDescription 对象,描述连接的本地端的待处理配置更改。这并不描述连接的当前状态,而是描述其在不久的将来可能存在的状态。

pendingRemoteDescription 只读

返回一个 RTCSessionDescription 对象,描述连接的远程端的待处理配置更改。这并不描述连接的当前状态,而是描述其在不久的将来可能存在的状态。

remoteDescription 只读

返回一个 RTCSessionDescription 对象,描述连接的远程端会话,包括配置和媒体信息。如果尚未设置,则返回 null

sctp 只读

返回一个 RTCSctpTransport 对象,描述正在发送和接收 SCTP 数据的 SCTP 传输层。如果尚未协商 SCTP,则此值为 null

signalingState 只读

静态方法

实例方法

创建一个 X.509 证书及其对应的私钥,返回一个 Promise,一旦生成,它就会解析为新的 RTCCertificate

addIceCandidate()

也继承了 EventTarget 的方法。

addTrack()

将新的 MediaStreamTrack 添加到将传输到另一方的一组轨道中。

addTransceiver()

创建一个新的 RTCRtpTransceiver 并将其添加到与连接关联的转发器集合中。每个转发器都代表一个双向流,与之关联的既有 RTCRtpSender,又有 RTCRtpReceiver

close()

关闭当前的对等连接。

createAnswer()

启动创建对来自远程对等方的报价的 SDP 应答,该报价是在 WebRTC 连接的报价/应答协商期间接收到的。应答包含有关已附加到会话的任何媒体、浏览器支持的编解码器和选项以及已收集到的任何 ICE 候选者的信息。

createDataChannel()

启动创建与远程对等方链接的新通道,可以通过该通道传输任何类型的数据。这对于后端内容(如图像、文件传输、文本聊天、游戏更新包等)很有用。

createOffer()

启动创建用于启动与远程对等方的全新 WebRTC 连接的 SDP 报价。SDP 报价包含有关已附加到 WebRTC 会话的任何 MediaStreamTrack 对象、浏览器支持的编解码器和选项以及 ICE 代理已收集到的任何候选者的信息,目的是通过信令通道发送到潜在的对等方以请求连接或更新现有连接的配置。

getConfiguration()

返回一个对象,该对象指示连接的当前配置。

getIdentityAssertion()

启动收集身份断言并返回一个 Promise,该对象解析为以字符串编码的身份断言。只有当 signalingState 不为 closed 时,此方法才有效。

getReceivers()

返回一个 RTCRtpReceiver 对象数组,每个对象都代表一个 RTP 接收器。

getSenders()

返回一个 RTCRtpSender 对象数组,每个对象都代表负责传输一条轨道数据的 RTP 发送器。

getStats()

返回一个 Promise,该对象解析为提供有关整体连接或指定 MediaStreamTrack 的统计信息的數據。

getTransceivers()

返回正在用于在连接上发送和接收数据的全部 RTCRtpTransceiver 对象列表。

removeTrack()

指示连接的本地端停止从指定轨道发送媒体,而不会实际从 getSenders() 报告的发送器列表中移除相应的 RTCRtpSender。如果轨道已停止或不在连接的发送器列表中,则此方法无效。

restartIce()

允许轻松地请求在连接的两端重新执行 ICE 候选者收集。通过允许调用方或接收方使用相同的方法来触发 ICE 重启,从而简化了此过程。

setConfiguration()

根据指定对象中包含的值设置连接的当前配置。这使您可以更改连接使用的 ICE 服务器以及要使用的传输策略。

setIdentityProvider()

将身份提供商 (IdP) 设置为参数中给定的三元组:其名称、用于与其通信的协议以及用户名。协议和用户名是可选的。

setLocalDescription()

更改与连接关联的本地描述。此描述指定连接本地端的属性,包括媒体格式。它返回一个 Promise,该对象在描述异步更改后完成。

setRemoteDescription()

将指定的会话描述设置为远程对等方的当前报价或应答。描述指定连接远程端的属性,包括媒体格式。它返回一个 Promise,该对象在描述异步更改后完成。

已弃用的方法

addStream() 已弃用 非标准

添加 MediaStream 作为音频或视频的本地源。您应该为要发送到远程对等方的每个轨道分别使用 addTrack(),而不是使用此已弃用的方法。

createDTMFSender() 已弃用

创建一个新的 RTCDTMFSender,它与特定的 MediaStreamTrack 关联,能够通过连接发送 DTMF 电话信令。

removeStream() 已弃用 非标准

移除 MediaStream 作为音频或视频的本地源。由于此方法已弃用,您应该改为使用 removeTrack()

事件

使用 addEventListener() 或通过将事件侦听器分配到此接口的 oneventname 属性来侦听这些事件。

connectionstatechange

RTCPeerConnection 的整体连接状态发生变化时发送。

datachannel

当远程对等方将 RTCDataChannel 添加到连接时发送。

icecandidate

发送请求将指定的候选者传输到远程对等方。

icecandidateerror

如果在 ICE 候选者收集过程中发生错误,则将其发送到连接。事件描述了错误。

iceconnectionstatechange

ICE 连接的状态发生变化时发送,例如断开连接时。

icegatheringstatechange

ICE 层的收集状态(由 iceGatheringState 反映)发生变化时发送。这表示 ICE 协商是否尚未开始 (new)、已开始收集候选者 (gathering) 或已完成 (complete)。

negotiationneeded

当需要执行 ICE 连接的协商或重新协商时发送;这可能发生在首次打开连接时,以及在需要适应不断变化的网络条件时。

signalingstatechange

当连接的 ICE 信令状态发生变化时发送。

track

在将新的轨道添加到构成连接的 RTCRtpReceiver 实例之一后发送。

已弃用的事件

addstream 已弃用 非标准

当新的 MediaStream 已添加到连接时发送。您应该侦听 track 事件,而不是侦听此已弃用的事件;对于添加到连接的每个 MediaStreamTrack,都会发送一个事件。

removestream 已弃用 非标准

MediaStream 从连接中移除时发送。您应该侦听每个流上的 removetrack 事件,而不是侦听此已弃用的事件。

规范

规范
WebRTC:浏览器中的实时通信
# interface-definition

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅