RTCPeerConnection
基线 广泛可用
此功能已发展成熟,并在许多设备和浏览器版本中运行良好。它自 2020 年 1 月.
报告反馈
构造函数
RTCPeerConnection()
-
RTCPeerConnection
接口表示本地计算机和远程对等体之间的 WebRTC 连接。它提供用于连接到远程对等体、维护和监控连接以及在不再需要时关闭连接的方法。
实例属性
返回一个新的 RTCPeerConnection
,表示本地设备和远程对等体之间的连接。
- 也继承了
EventTarget
的属性。 - 返回一个布尔值,指示远程对等体是否可以接受 trickled ICE 候选。
- 通过返回以下字符串之一来指示对等连接的当前状态:
new
、connecting
、connected
、disconnected
、failed
或closed
。 - 返回一个
RTCSessionDescription
对象,描述自上次此RTCPeerConnection
完成协商和连接到远程对等体以来最后一次成功协商的连接的本地端。还包括 ICE 代理可能已在此描述所代表的要约或应答首次实例化后生成的任何 ICE 候选列表。 - 返回一个
RTCSessionDescription
对象,描述自上次此RTCPeerConnection
完成协商和连接到远程对等体以来最后一次成功协商的连接的远程端。还包括 ICE 代理可能已在此描述所代表的要约或应答首次实例化后生成的任何 ICE 候选列表。 - 返回一个字符串,描述与此 RTCPeerConnection 关联的 ICE 代理的状态。它可以是以下值之一:
new
、checking
、connected
、completed
、failed
、disconnected
或closed
。 - 返回一个字符串,描述连接的 ICE 收集状态。这使您可以检测例如 ICE 候选收集何时完成。可能的值是:
new
、gathering
或complete
。 - 返回一个
RTCSessionDescription
,描述连接的本地端会话。如果尚未设置,则返回null
。 -
peerIdentity
只读 - 返回一个
Promise
,它解析为一个RTCIdentityAssertion
,其中包含标识远程对等体的字符串。一旦此 promise 成功解析,结果标识就是目标对等体标识,并且在连接持续期间不会更改。 - 返回一个
RTCSessionDescription
对象,描述连接的本地端的待处理配置更改。这并不描述连接的当前状态,而是描述其在不久的将来可能存在的状态。 - 返回一个
RTCSessionDescription
对象,描述连接的远程端的待处理配置更改。这并不描述连接的当前状态,而是描述其在不久的将来可能存在的状态。 - 返回一个
RTCSessionDescription
对象,描述连接的远程端会话,包括配置和媒体信息。如果尚未设置,则返回null
。 -
sctp
只读 - 返回一个
RTCSctpTransport
对象,描述正在发送和接收 SCTP 数据的 SCTP 传输层。如果尚未协商 SCTP,则此值为null
。
静态方法
返回一个字符串,描述连接或重新连接到另一个对等体时连接本地端信令过程的状态。它可以是以下值之一:
stable
、have-local-offer
、have-remote-offer
、have-local-pranswer
、have-remote-pranswer
或closed
。-
RTCPeerConnection.generateCertificate()
实例方法
创建一个 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 表格仅在浏览器中加载
另请参阅
- https://github.com/jesup/nightly-gupshup/blob/master/static/js/chat.js
- 开始使用 WebRTC
- TutorRoom:Node.js HTML 视频捕获、对等视频和文件共享应用程序 (GitHub 上的源代码)