From 33058f2b292b3a581333bdfb21b8f671898c5060 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:40:17 -0500 Subject: initial commit --- .../rtcpeerconnection/addicecandidate/index.html | 203 +++++++++++ .../web/api/rtcpeerconnection/addtrack/index.html | 207 +++++++++++ .../cantrickleicecandidates/index.html | 102 ++++++ .../rtcpeerconnection/connectionstate/index.html | 64 ++++ .../rtcpeerconnection/createdatachannel/index.html | 146 ++++++++ .../api/rtcpeerconnection/createoffer/index.html | 152 +++++++++ .../currentlocaldescription/index.html | 80 +++++ .../getdefaulticeservers/index.html | 57 ++++ .../api/rtcpeerconnection/getreceivers/index.html | 60 ++++ .../iceconnectionstate/index.html | 110 ++++++ .../rtcpeerconnection/icegatheringstate/index.html | 57 ++++ files/zh-cn/web/api/rtcpeerconnection/index.html | 377 +++++++++++++++++++++ .../api/rtcpeerconnection/onaddstream/index.html | 103 ++++++ .../api/rtcpeerconnection/ondatachannel/index.html | 112 ++++++ .../rtcpeerconnection/onicecandidate/index.html | 65 ++++ .../web/api/rtcpeerconnection/ontrack/index.html | 106 ++++++ .../api/rtcpeerconnection/peeridentity/index.html | 72 ++++ .../rtcpeerconnection/remotedescription/index.html | 71 ++++ .../api/rtcpeerconnection/removestream/index.html | 118 +++++++ .../rtcpeerconnection/rtcpeerconnection/index.html | 131 +++++++ .../rtcpeerconnection/setconfiguration/index.html | 99 ++++++ .../setremotedescription/index.html | 127 +++++++ 22 files changed, 2619 insertions(+) create mode 100644 files/zh-cn/web/api/rtcpeerconnection/addicecandidate/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/addtrack/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/cantrickleicecandidates/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/connectionstate/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/createdatachannel/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/createoffer/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/currentlocaldescription/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/getdefaulticeservers/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/getreceivers/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/iceconnectionstate/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/icegatheringstate/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/onaddstream/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/ondatachannel/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/onicecandidate/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/ontrack/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/peeridentity/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/remotedescription/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/removestream/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/rtcpeerconnection/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/setconfiguration/index.html create mode 100644 files/zh-cn/web/api/rtcpeerconnection/setremotedescription/index.html (limited to 'files/zh-cn/web/api/rtcpeerconnection') diff --git a/files/zh-cn/web/api/rtcpeerconnection/addicecandidate/index.html b/files/zh-cn/web/api/rtcpeerconnection/addicecandidate/index.html new file mode 100644 index 0000000000..c648d7aac4 --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/addicecandidate/index.html @@ -0,0 +1,203 @@ +--- +title: RTCPeerConnection.addIceCandidate() +slug: Web/API/RTCPeerConnection/addIceCandidate +translation_of: Web/API/RTCPeerConnection/addIceCandidate +--- +

{{APIRef("WebRTC")}}{{SeeCompatTable}}

+ +

当本机当前页面的 {{domxref("RTCPeerConnection")}} 接收到一个从远端页面通过信号通道发来的新的 ICE 候选地址信息，本机可以通过调用RTCPeerConnection.addIceCandidate() 来添加一个 {{Glossary("ICE")}} 代理。 This adds this new remote candidate to the RTCPeerConnection's remote description, which describes the state of the remote end of the connection.

+ +

If the value of the specified object's {{domxref("RTCIceCandidate.candidate", "candidate")}} is an empty string (""), it signals that all remote candidates have been delivered.

+ +

During negotiation, your app will likely receive many candidates which you'll deliver to the ICE agent in this way, allowing it to build up a list of potential connection methods. This is covered in more detail in the articles WebRTC connectivity and Signaling and video calling.

+ +

Syntax

+ +
aPromise = pc.addIceCandidate(candidate);
+
+addIceCandidate(candidate, successCallback, failureCallback); {{deprecated_inline}}
+
+ +

Parameters

+ +
+
candidate
+
An object conforming to the {{domxref("RTCIceCandidateInit")}} dictionary; the contents of the object should be constructed from a message received over the signaling channel, describing a newly received ICE candidate that's ready to be delivered to the local ICE agent.
+
+ +

Deprecated parameters

+ +

在一些老旧的代码和文档中, 你可能会看到一个回调函数(callback)版本的函数。这种函数是过期的，强烈建议不要使用。你应该更新你的代码，使用 {{jsxref("Promise")}}-版本的 addIceCandidate() . 这个版本的参数格式附在下面, 方便你更新已有的代码.

+ +
+
successCallback {{deprecated_inline}}
+
A function to be called when the ICE candidate has been successfully added. This function receives no input parameters and doesn't return a value.
+
failureCallback {{deprecated_inline}}
+
A function to be called if attempting to add the ICE candidate fails. Receives as input a {{domxref("DOMException")}} object describing why failure occurred.
+
+ +

Return value

+ +

A {{jsxref("Promise")}} which is fulfilled when the candidate has been successfully added to the remote peer's description by the ICE agent. The promise does not receive any input parameters.

+ +

Exceptions

+ +

When an error occurs while attempting to add the ICE candidate, the {{jsxref("Promise")}} returned by this method is rejected, returning one of the errors below as the {{domxref("DOMException.name", "name")}} attribute in the specified {{domxref("DOMException")}} object passed to the rejection handler.

+ +
+
TypeError
+
The specified candidate doesn't have values for both {{domxref("RTCIceCandidate.sdpMid", "sdpMid")}} and {{domxref("RTCIceCandidate.sdpMLineIndex", "sdpMLineIndex")}}.
+
InvalidStateError
+
The RTCPeerConnection currently has no remote peer established ({{domxref("RTCPeerConnection.remoteDescription", "remoteDescription")}} is null).
+
OperationError
+
A non-null value was specified for {{domxref("RTCIceCandidate.sdpMid", "sdpMid")}}, but the value doesn't match the mid of any media description in the remoteDescription, or {{domxref("RTCIceCandidate.sdpMLineIndex", "sdpMLineIndex")}} is greater than or equal to the number of media descriptions in remoteDescription. This error can also be thrown if a value is given for {{domxref("RTCIceCandidate.ufrag", "ufrag")}} that doesn't match the value of ufrag in any of the remote description being selected.
+
+ OperationError also occurs if the attempt to add the candidate fails for any other reason.
+
+ +

Example

+ +

下段代码会展示如何使用一个SDP字符串(这个字符串包含了候选的描述)去构建一个候选对象。这个字符串来自于信道(signaling channel)。

+ +
// |receivedSDP| is an SDP string received over the signaling channel
+// by our handler for "new ICE candidate" messages.
+
+let candidate = new RTCIceCandidate(receivedSDP);
+
+pc.addIceCandidate(candidate).then(_=>{
+  // Do stuff when the candidate is successfully passed to the ICE agent
+}).catch(e=>{
+  console.log("Error: Failure during addIceCandidate()");
+});
+ +

Specifications

+ + + + + + + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-addIceCandidate-Promise-void--RTCIceCandidateInit-RTCIceCandidate-candidate', 'RTCPeerConnection.addIceCandidate()') }}{{ Spec2('WebRTC 1.0') }}Initial specification.
{{SpecName("WebRTC 1.0", "#widl-RTCPeerConnection-addIceCandidate-void-RTCIceCandidateInit-RTCIceCandidate-candidate-VoidFunction-successCallback-RTCPeerConnectionErrorCallback-failureCallback", "RTCPeerConnection.addIceCandidate()")}} {{deprecated_inline}}{{Spec2("WebRTC 1.0")}}Initial specification.
+ +

Browser compatibility

+ +

{{ CompatibilityTable}}

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{ CompatVersionUnknown}}[1]{{CompatVersionUnknown}}{{ CompatGeckoDesktop(22) }} [2]{{ CompatNo}}{{ CompatVersionUnknown}}{{ CompatUnknown}}
Promise-based version{{CompatChrome(50)}}{{CompatUnknown}}{{ CompatGeckoDesktop(37)}}{{ CompatUnknown}}{{ CompatUnknown}}{{ CompatUnknown}}
{{domxref("RTCIceCandidateInit")}} as input{{CompatUnknown}}{{CompatUnknown}}{{CompatGeckoDesktop(53)}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FeatureAndroid WebviewChrome for AndroidEdgeFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatVersionUnknown}}[1]{{ CompatVersionUnknown}}[1]{{CompatVersionUnknown}}{{ CompatGeckoMobile(22)}}{{ CompatNo}}{{ CompatUnknown}}{{ CompatUnknown}}
Promise-based version{{CompatChrome(50)}}{{CompatChrome(50)}}{{CompatUnknown}}{{CompatGeckoMobile(37)}}{{ CompatUnknown}}{{ CompatUnknown}}{{ CompatUnknown}}
{{domxref("RTCIceCandidateInit")}} as input{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatGeckoMobile(53)}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
+
+ +

[1] Though this method is not prefixed, the interface it belongs to was until Chrome 56.

+ +

[2] Though this method is not prefixed, the interface it belongs to was until Firefox 44.

+ +

See also

+ + diff --git a/files/zh-cn/web/api/rtcpeerconnection/addtrack/index.html b/files/zh-cn/web/api/rtcpeerconnection/addtrack/index.html new file mode 100644 index 0000000000..df295671eb --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/addtrack/index.html @@ -0,0 +1,207 @@ +--- +title: RTCPeerConnection.addTrack() +slug: Web/API/RTCPeerConnection/addTrack +translation_of: Web/API/RTCPeerConnection/addTrack +--- +
{{APIRef("WebRTC")}}
+ +

{{domxref("RTCPeerConnection")}} 对象的addTrack()方法将一个新的媒体音轨添加到一组音轨中，这些音轨将被传输给另一个对等点。

+ +
+

注意:通过触发一个{{event("negotiationneeded")}}事件，向连接添加一个跟踪将触发重新协商。详情请参见{{SectionOnPage("/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling", "Starting negotiation")}}。

+
+ +

语法

+ +
rtpSender = rtcPeerConnection.addTrack(track, stream...);
+ +

参数

+ +
+
track
+
一个{{domxref("MediaStreamTrack")}}对象，表示要添加到对等连接的媒体轨道。
+
stream... {{optional_inline}}
+
一个或多个本地的{{domxref("MediaStream")}}对象，该轨迹应添加到其中。
+
+ +

指定的track不一定已经是任何指定streams的一部分。相反，streams只是在连接的接收端将轨迹分组在一起的一种方式，以确保它们是同步的。在连接的本地端添加到相同流的任何轨道都将位于远程端相同的流上。

+ +

返回值

+ +

将用于传输媒体数据的{{domxref("RTCRtpSender")}}对象。

+ +
+

注意:每个RTCRtpSender都与{{domxref("RTCRtpReceiver")}}配对，组成{{domxref("RTCRtpTransceiver")}}。关联的接收方处于静默状态(指示它不能发送数据包)，直到或除非远程对等方向接收方添加一个或多个流。

+
+ +

异常

+ +
+
InvalidAccessError
+
指定的轨道(或它的所有底层流)已经是{{domxref("RTCPeerConnection")}}的一部分。
+
InvalidStateError
+
{{domxref("RTCPeerConnection")}}被关闭。
+
+ +

使用笔记

+ +

向多个流添加轨道

+ +

在track参数之后，您可以选择指定一个或多个{{domxref("MediaStream")}}对象来添加track。只有轨道从一个点发送到另一个点，而不是一个媒体流。由于流是特定于每个对等点的，因此指定一个或多个流意味着另一个对等点将在连接的另一端自动创建一个相应的流(或多个流)，然后自动将接收到的轨道添加到这些流中。

+ +

无流承载的轨道

+ +

如果没有指定媒体流，则轨道是无流的。这是完全可以接受的，尽管要由远程对等点决定将轨道插入到哪个流(如果有的话)。当构建一个多类型的简单应用只有一个媒体流时，使用addTrack()是一个非常常用的办法。例如，如果您与远程对等点共享的只是带有音频轨道和视频轨道的单个流，那么您不需要管理流中的哪个轨道，所以您不妨让transceriver为您处理它。

+ +

下面是一个使用{{domxref("MediaDevices.getUserMedia", "getUserMedia()")}}从用户的摄像机和麦克风获取一个流，然后将流中的每条轨迹添加到对等连接，而不为每条轨迹指定一个流:

+ +
async openCall(pc) {
+  const gumStream = await navigator.mediaDevices.getUserMedia(
+                          {video: true, audio: true});
+  for (const track of gumStream.getTracks()) {
+    pc.addTrack(track);
+  }
+}
+ +

结果是一组没有流关联的跟踪被发送到远程对等点。远程对等点上的{{event("track")}}事件的处理程序将负责决定将每个跟踪添加到哪个流中，即使这意味着只是将它们全部添加到同一个流中。{{domxref("RTCPeerConnection.ontrack", "ontrack")}}方法如下:

+ +
let inboundStream = null;
+
+pc.ontrack = ev => {
+  if (ev.streams && ev.streams[0]) {
+    videoElem.srcObject = ev.streams[0];
+  } else {
+    if (!inboundStream) {
+      inboundStream = new MediaStream();
+      videoElem.srcObject = inboundStream;
+    }
+    inboundStream.addTrack(ev.track);
+  }
+}
+ +

在这里，如果指定了流，则track事件处理程序将跟踪添加到事件指定的第一个流。否则，在第一次调用ontrack时，将创建一个新流并附加到视频元素，然后将音轨添加到新流中。从那时起，新的堆track被添加到这个流中。

+ +

你也可以为每个接收到的track创建一个新的流:

+ +
pc.ontrack = ev => {
+  if (ev.streams && ev.streams[0]) {
+    videoElem.srcObject = ev.streams[0];
+  } else {
+    let inboundStream = new MediaStream(ev.track);
+    videoElem.srcObject = inboundStream;
+  }
+}
+ +

将track与特定的stream相关联

+ +

通过指定一个流并允许{{domxref("RTCPeerConnection")}}为您创建流，流的跟踪关联将由WebRTC基础设施自动为您管理。这包括对收发器的{{domxref("RTCRtpTransceiver.direction","direction")}} 的更改和被停止使用{{domxref("RTCPeerConnection.removeTrack","removeTrack()")}}。

+ +

例如，考虑应用程序可能使用的这个函数，通过{{domxref("RTCPeerConnection")}}将设备的摄像头和麦克风输入流化为远程对等点:

+ +
async openCall(pc) {
+  const gumStream = await navigator.mediaDevices.getUserMedia(
+                          {video: true, audio: true});
+  for (const track of gumStream.getTracks()) {
+    pc.addTrack(track, gumStream);
+  }
+}
+ +

远程对等点然后可以使用一个看起来像这样的{{event("track")}}事件处理程序:

+ +
pc.ontrack = ({streams: [stream]} => videoElem.srcObject = stream;
+ +

这将把视频元素的当前流设置为包含已添加到连接中的音轨的流。

+ +

重用发送方

+ +

这种方法可以返回一个新的RTCRtpSender，或者在非常特殊的情况下，返回一个尚未用于传输数据的现有的兼容发送方。兼容的可重用RTCRtpSender实例满足以下条件:

+ + + +

如果所有这些条件都满足，发送方会被重用，这将导致现有RTCRtpSender和它的RTCRtpTransceiver发生这些变化:

+ + + +

新发送方

+ +

如果现有的发送方不存在可重用，则创建一个新的发送方。这也会导致必须存在的关联对象的创建。创建新发送方的过程会导致以下更改:

+ + + +
+
+ +

实例

+ +

这个例子是从文章中给出的Signaling and video calling及其相应的示例代码中提取的。它来自那里的handleVideoOfferMsg()方法，该方法在从远程对等方接收到报价消息时被调用。

+ +
var mediaConstraints = {
+  audio: true,            // We want an audio track
+  video: true             // ...and we want a video track
+};
+
+var desc = new RTCSessionDescription(sdp);
+
+pc.setRemoteDescription(desc).then(function () {
+  return navigator.mediaDevices.getUserMedia(mediaConstraints);
+})
+.then(function(stream) {
+  previewElement.srcObject = stream;
+
+  stream.getTracks().forEach(track => pc.addTrack(track, stream));
+})
+ +

这段代码获取从远程对等方接收到的SDP，并构造一个新的{{domxref("RTCSessionDescription")}}传递到{{domxref("RTCPeerConnection.setRemoteDescription", "setRemoteDescription()")}}。成功之后，它使用{{domxref(" mediadevic. getusermedia()")}}获得对本地摄像头和麦克风的访问。

+ +

如果成功，结果流将被分配为变量previewElement引用的{{HTMLElement("video")}}元素的源。

+ +

最后一步是开始通过对等连接向调用者发送本地视频。通过遍历{{domxref("MediaStream.getTracks()")}}返回的列表，并将它们与作为其组件的流一起传递给addTrack()，从而在流中添加每条跟踪。

+ +

技术规范

+ + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{ SpecName('WebRTC 1.0', '#dom-rtcpeerconnection-addtrack', 'RTCPeerConnection.addTrack()') }}{{ Spec2('WebRTC 1.0') }}Initial specification.
+ +

浏览器支持

+ + + +

{{Compat("api.RTCPeerConnection.addTrack")}}

+ +

参考

+ + diff --git a/files/zh-cn/web/api/rtcpeerconnection/cantrickleicecandidates/index.html b/files/zh-cn/web/api/rtcpeerconnection/cantrickleicecandidates/index.html new file mode 100644 index 0000000000..c7742e042b --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/cantrickleicecandidates/index.html @@ -0,0 +1,102 @@ +--- +title: RTCPeerConnection.canTrickleIceCandidates +slug: Web/API/RTCPeerConnection/canTrickleIceCandidates +translation_of: Web/API/RTCPeerConnection/canTrickleIceCandidates +--- +
{{APIRef("WebRTC")}}
+ +
只读的 {{domxref("RTCPeerConnection")}} 属性 canTrickleIceCandidates 返回一个{{jsxref("Boolean")}}，它指示远程对等端是否可以接受 trickled ICE candidates 。
+
+ICE trickling是在初始发送或回应已经发送给其他设备之后继续发送候选的过程。
+
+仅在调用{{domxref("RTCPeerConnection.setRemoteDescription()")}}之后才设置此属性。 理想情况下，您的信令协议提供了一种检测滴流支持的方法，因此您无需依赖此属性。 WebRTC浏览器将始终支持trickle ICE。 如果不支持滴流，或者您无法辨别，则可以检查此属性的伪值，然后等待{{domxref("RTCPeerConnection.iceGatheringState","iceGatheringState")}}的值更改在创建和发送之前“完成”。
+ +
这样，发送信息包含所有候选。
+ + + +

语法

+ +
 var canTrickle = RTCPeerConnection.canTrickleIceCandidates;
+ +

值

+ +

{{jsxref("Boolean")}}　如果远程对等体可以接受滴入的ICE candidate，则为true;如果不能，则为false。 如果尚未建立远程对等方，则此值为null。

+ +
+

Note: 一旦本地对等方调用{{domxref("RTCPeerConnection.setRemoteDescription()")}}，就确定该属性的值; ICE代理使用所提供的描述来确定远程对等体是否支持滴入的ICE candidates。

+
+ +

用例

+ +
var pc = new RTCPeerConnection();
+// The following code might be used to handle an offer from a peer when
+// it isn't known whether it supports trickle ICE.
+pc.setRemoteDescription(remoteOffer)
+  .then(_ => pc.createAnswer())
+  .then(answer => pc.setLocalDescription(answer))
+  .then(_ =>
+    if (pc.canTrickleIceCandidates) {
+      return pc.localDescription;
+    }
+    return new Promise(r => {
+      pc.addEventListener('icegatheringstatechange', e => {
+        if (e.target.iceGatheringState === 'complete') {
+          r(pc.localDescription);
+        }
+      });
+    });
+  })
+  .then(answer => sendAnswerToPeer(answer)) // signaling message
+  .catch(e => handleError(e));
+
+pc.addEventListener('icecandidate', e => {
+  if (pc.canTrickleIceCandidates) {
+    sendCandidateToPeer(e.candidate); // signaling message
+  }
+});
+
+ + + + + + + + +
+

规范

+ 		+
+
+ + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-canTrickleIceCandidates', 'RTCPeerConnection.canTrickleIceCandidates') }}{{ Spec2('WebRTC 1.0') }}Initial specification.
+ +

浏览器兼容性

+ + + +

{{Compat("api.RTCPeerConnection.canTrickleIceCandidates")}}

+ +

相关阅读

+ + diff --git a/files/zh-cn/web/api/rtcpeerconnection/connectionstate/index.html b/files/zh-cn/web/api/rtcpeerconnection/connectionstate/index.html new file mode 100644 index 0000000000..b61466213e --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/connectionstate/index.html @@ -0,0 +1,64 @@ +--- +title: RTCPeerConnection.connectionState +slug: Web/API/RTCPeerConnection/connectionState +translation_of: Web/API/RTCPeerConnection/connectionState +--- +

{{APIRef("WebRTC")}}

+ +

 

+ +

connectionState 只读，说明当前连接状态。状态值参见RTCPeerConnectionState ，值由一个peer connection返回。

+ +

值变化时，一个connectionstatechange 事件发送给RTCPeerConnection对象实例中。

+ +

Syntax

+ +
var connectionState = RTCPeerConnection.connectionState;
+ +

Value

+ +

The current state of the connection, as a value from the enum RTCPeerConnectionState.

+ +

{{page("/en-US/docs/Web/API/RTCPeerConnection", "RTCPeerConnectionState enum", 0, 1)}}

+ +

Example

+ +
var pc = new RTCPeerConnection(configuration);
+
+/* ... */
+
+var connectionState = pc.connectionState;
+ +

Specifications

+ + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-connectionState', 'RTCPeerConnection.connectionState') }}{{ Spec2('WebRTC 1.0') }}Initial specification.
+ +

Browser compatibility

+ + + +

{{Compat("api.RTCPeerConnection.connectionState")}}

+ +

See also

+ + diff --git a/files/zh-cn/web/api/rtcpeerconnection/createdatachannel/index.html b/files/zh-cn/web/api/rtcpeerconnection/createdatachannel/index.html new file mode 100644 index 0000000000..35f2d35441 --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/createdatachannel/index.html @@ -0,0 +1,146 @@ +--- +title: RTCPeerConnection.createDataChannel() +slug: Web/API/RTCPeerConnection/createDataChannel +translation_of: Web/API/RTCPeerConnection/createDataChannel +--- +

{{APIRef("WebRTC")}}{{SeeCompatTable}}

+ +

{{domxref("RTCPeerConnection")}} 的 createDataChannel() 方法创建一个可以发送任意数据的数据通道(data channel)。常用于后台传输内容, 例如: 图像, 文件传输, 聊天文字, 游戏数据更新包, 等等。

+ +

基于某个连接创建第一个data channel时, 会通过发送一个{{event("negotiationneeded")}} event来开始重新谈判(renegotiation)。

+ +

语法

+ +
dataChannel = RTCPeerConnection.createDataChannel(label[, options]);
+ +

参数

+ +
+
label
+
一个便于理解的通道名. 该字符串不能长于 65,535 字节.
+
options {{optional_inline}}
+
提供data channel设置的一个 RTCDataChannelInit dictionary 
+
+ +

RTCDataChannelInit dictionary

+ +

RTCDataChannelInit 字典提供以下字段, 用以构造可选的options参数来设置data channel以满足你的需求:

+ +
+
ordered {{optional_inline}}
+
表示通过 {{domxref("RTCDataChannel")}} 的信息的到达顺序需要和发送顺序一致(true), 或者到达顺序不需要和发送顺序一致 (false). 默认: true.
+
maxPacketLifeTime {{optional_inline}}
+
The maximum number of milliseconds that attempts to transfer a message may take in unreliable mode. While this value is a 16-bit unsigned number, each user agent may clamp it to whatever maximum it deems appropriate. Default: null.
+
maxRetransmits {{optional_inline}}
+
The maximum number of times the user agent should attempt to retransmit a message which fails the first time in unreliable mode. While this value is a16-bit unsigned number, each user agent may clamp it to whatever maximum it deems appropriate. Default: null.
+
protocol {{optional_inline}}
+
The name of the sub-protocol being used on the {{domxref("RTCDataChannel")}}, if any; otherwise, the empty string (""). Default: empty string, "". This string may not be longer than 65,535 bytes.
+
negotiated {{optional_inline}}
+
By default (false), data channels are negotiated in-band, where one side calls createDataChannel, and the other side listens to the {{domxref("RTCDataChannelEvent")}} event using the ondatachannel EventHandler . Alternatively (true), they can be negotiated out of-band, where both sides call createDataChannel with an agreed-upon id. Default: false.
+
id {{optional_inline}}
+
An 16-bit numeric ID for the channel; permitted values are 0-65534. If you don't include this option, the user agent will select an ID for you.
+
+ +
+

The options which can be configured using the RTCDataChannelInit dictionary represent the script-settable subset of the properties on the {{domxref("RTCDataChannel")}} interface.

+
+ +

Return value

+ +

A new {{domxref("RTCDataChannel")}} object with the specified label, configured using the options specified by options if that parameter is included; otherwise, the defaults listed above are established.

+ +

Exceptions

+ +
+
InvalidStateError
+
The {{domxref("RTCPeerConnection")}} is closed.
+
TypeError
+
This can happen in a couple of situations: +
    +
  • The label and/or protocol string is too long; these cannot be longer than 65,535 bytes (bytes, rather than characters).
    • +
  • The id is 65535. While this is a valid unsigned 16-bit value, it's not a permitted value for id.
    • +
+
+
SyntaxError
+
Values were specified for both the maxPacketLifeTime and maxRetransmits options. You may only specify a non-null value for one of these.
+
ResourceInUse
+
An id was specified, but another {{domxref("RTCDataChannel")}} is already using the same value.
+
OperationError
+
Either the specified id is already in use or, if no id was specified, the WebRTC layer was unable to automatically generate an ID because all IDs are in use.
+
+ +

Examples

+ +

This example shows how to create a data channel and set up handlers for the {{event("open")}} and {{event("message")}} events to send and receive messages on it (For brievity, the example assumes onnegotiationneeded is set up).

+ +
// Offerer side
+
+var pc = new RTCPeerConnection(options);
+var channel = pc.createDataChannel("chat");
+channel.onopen = function(event) {
+  channel.send('Hi you!');
+}
+channel.onmessage = function(event) {
+  console.log(event.data);
+}
+ +
// Answerer side
+
+var pc = new RTCPeerConnection(options);
+pc.ondatachannel = function(event) {
+  var channel = event.channel;
+  channel.onopen = function(event) {
+    channel.send('Hi back!');
+  }
+  channel.onmessage = function(event) {
+    console.log(event.data);
+  }
+}
+ +

Alternatively, more symmetrical out-of-band negotiation can be used, using an agreed-upon id (0 here):

+ +
// Both sides
+
+var pc = new RTCPeerConnection(options);
+var channel = pc.createDataChannel("chat", {negotiated: true, id: 0});
+channel.onopen = function(event) {
+  channel.send('Hi!');
+}
+channel.onmessage = function(event) {
+  console.log(event.data);
+}
+ +

For a more thorough example showing how the connection and channel are established, see A simple RTCDataChannel sample.

+ +

Specifications

+ + + + + + + + + + + + + + +
SpecificationStatusComment
{{SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-createDataChannel-RTCDataChannel-DOMString-label-RTCDataChannelInit-dataChannelDict', 'createDataChannel()')}}{{Spec2('WebRTC 1.0')}}Initial definition.
+ +

Browser compatibility

+ +
+ + +

{{Compat("api.RTCPeerConnection.createDataChannel")}}

+
+ +

See also

+ + diff --git a/files/zh-cn/web/api/rtcpeerconnection/createoffer/index.html b/files/zh-cn/web/api/rtcpeerconnection/createoffer/index.html new file mode 100644 index 0000000000..739b0fef65 --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/createoffer/index.html @@ -0,0 +1,152 @@ +--- +title: RTCPeerConnection.createOffer() +slug: Web/API/RTCPeerConnection/createOffer +tags: + - API + - Media + - RTCPeerConnection + - Reference + - SDP + - WebRTC + - createOffer +translation_of: Web/API/RTCPeerConnection/createOffer +--- +
{{APIRef("WebRTC")}}
+ +
{{domxref("RTCPeerConnection")}}接口的createOffer（）方法启动创建一个{{Glossary("SDP")}} offer，目的是启动一个新的WebRTC去连接远程端点。SDP offer包含有关已附加到WebRTC会话，浏览器支持的编解码器和选项的所有{{domxref("MediaStreamTrack")}}s信息，以及{{Glossary("ICE")}} 代理，目的是通过信令信道发送给潜在远程端点，以请求连接或更新现有连接的配置。
+ +
+ +
返回值是一个{{domxref("Promise")}}，创建 offer 后，将使用包含新创建的要约的{{domxref("RTCSessionDescription")}}对象来解析该返回值。
+ +

Syntax

+ +
aPromise = myPeerConnection.createOffer([options]);
+
+myPeerConnection.createOffer(successCallback, failureCallback, [options]) {{deprecated_inline}}
+
+ +

Parameters

+ +
+
选项 {{optional_inline}}
+
RTCOfferOptions 词典提供要约所要求的选项。
+
+ +

RTCOfferOptions 词典

+ +

RTCOfferOptions 词典被用于自定义通过此方法创建offer。

+ +
+
iceRestart {{optional_inline}}
+
要在活动连接上重新启动ICE，请将其设置为true。 这将导致返回的 offer 与已经存在的凭证不同。 如果您应用返回的offer，则ICE将重新启动。 指定false以保留相同的凭据，因此不重新启动ICE。 默认值为false。
+
offerToReceiveAudio {{optional_inline}} (Legacy)
+
+

传统的布尔选项，用于控制是否向远程对等方提供尝试发送音频的机会。 如果该值为false，即使本地端将发送音频数据，也不会提供远程端点发送音频数据。 如果此值为true，即使本地端不会发送音频数据，也将向远程端点发送音频数据。 默认行为是仅在本地发送音频时才提供接收音频，否则不提供。

+
+
为了在现代实现中模拟此行为，该成员的值为false将设置所有现有音频收发器的方向以排除接收（即，设置为“仅发送”或“无效”）。
+
在现代实现中，此成员的值为true的存在将确保至少有一个收发器集可以接收尚未停止的音频，如果没有，则将创建一个。
+
+
笔记: 您不应该使用此旧版属性。取而代之, 用 {{domxref("RTCRtpTransceiver")}} 去控制是否接受传入的音频。
+
+
offerToReceiveVideo {{optional_inline}} (Legacy)
+
传统的布尔选项，用于控制是否向远程对等方提供尝试发送视频的机会。 如果此值为false，即使本地端将发送视频数据，也不会提供远程端点发送视频数据。 如果此值为true，即使本地端将不发送视频数据，也将向远程端点发送视频数据。 默认行为是仅在本地端正在发送视频时才提供接收视频，否则不提供。
+
为了在现代实现中模拟这种行为，该成员的值为false将设置所有现有视频收发器的方向以排除接收（即设置为“仅发送”或“无效”）。
+
在现代实现中，该成员的值为true的存在将确保至少有一个收发器集可以接收尚未停止的视频，如果没有，则将创建一个。
+
+
笔记: 您不应该使用此旧版属性。取而代之, 用 {{domxref("RTCRtpTransceiver")}} 去控制是否接受传入的视频。
+
+
voiceActivityDetection {{optional_inline}}
+
一些编解码器和硬件能够通过监视是否出现“静音”（或相对较低的声音水平）来检测音频何时开始和结束。 通过仅在实际有广播内容时发送音频数据，从而减少了用于音频的网络带宽。 但是，在某些情况下，这是不需要的。 例如，在音乐或其他非语音传输的情况下，这可能会导致重要的低音量声音丢失。 而且，紧急呼叫在安静时切勿切断音频。 此选项默认为true（启用语音活动检测）。
+
+ +
+
+

不推荐使用的参数

+ + +
+
+

在较早的代码和文档中，您可能会看到此函数的基于回调的版本。 不推荐使用并强烈建议不要使用它。 您应该更新任何现有代码，以使用基于 {{jsxref("Promise")}}的createOffer()版本。 下面介绍了这种形式的createOffer()的参数，以帮助更新现有代码。

+
+
+ +
+
successCallback {{deprecated_inline}}
+
{{domxref("RTCSessionDescriptionCallback")}}将传递一个描述新创建的offer的{{domxref("RTCSessionDescription")}}对象。
+
errorCallback {{deprecated_inline}}
+
{{domxref("RTCPeerConnectionErrorCallback")}}将会传递给一个{{domxref("DOMException")}}对象，该对象说明了创建offer的请求失败的原因。
+
options {{optional_inline}}
+
可选的RTCOfferOptions词典，提供 offer所要求的选项。
+
+ +

返回值

+ +

{{jsxref("Promise")}}的履行处理程序将接收符合{{domxref("RTCSessionDescriptionInit")}}字典的对象，该字典包含描述所生成 offer 的SDP。 收到的 offer 应通过信令服务器传递到。

+ +

异常

+ +

通过拒绝返回的承诺返回这些异常。 您的拒绝处理程序应检查收到的异常，以确定发生了哪些异常。

+ +
+
InvalidStateError
+
RTCPeerConnection 被关闭.
+
NotReadableError
+
没有提供用于保护连接的证书或一组证书，并且createOffer()无法创建新证书。 由于需要保护所有WebRTC连接，因此会导致错误。
+
OperationError
+
由于某些原因，检查系统状态以确定资源可用性以生成报价失败。
+
+ +

举例

+ +

在这里，我们看到了{{event("negotiationneeded")}}事件的处理程序，该处理程序创建了要约，并通过信令通道将其发送到远程系统。

+ +
+

笔记: 请记住，这是信令过程的一部分，传输层的实现细节完全由您决定。 在这种情况下，WebSocket连接用于向其他端点发送带有值为“ video-offer”的类型字段的{{Glossary("JSON")}}消息。 传递给sendToServer()函数的对象的内容，以及承诺履行处理程序中的所有其他内容，完全取决于您的设计。

+
+ +
  myPeerConnection.createOffer().then(function(offer) {
+    return myPeerConnection.setLocalDescription(offer);
+  })
+  .then(function() {
+    sendToServer({
+      name: myUsername,
+      target: targetUsername,
+      type: "video-offer",
+      sdp: myPeerConnection.localDescription
+    });
+  })
+  .catch(function(reason) {
+    // An error occurred, so handle the failure to connect
+  });
+ +

在此代码中，创建了offer，一旦成功，就将{{domxref("RTCPeerConnection")}}的本地端配置为通过传递要约进行匹配（使用符合{{domxref("RTCSessionDescriptionInit")}}）放入{{domxref("RTCPeerConnection.setLocalDescription", "setLocalDescription()")}}。 完成后，要约将通过信令通道发送到远程系统。 在这种情况下，使用名为sendToServer()的自定义函数。 信令服务器的实现独立于WebRTC规范，因此只要主叫方和潜在接收方都使用相同的offer，如何发送offer都无关紧要。

+ +

用 {{jsxref("Promise.catch()")}} 来捕获和处理错误.

+ +

请参阅 Signaling and video calling，以获取此摘录的完整示例。 这将帮助您了解此处的信令代码如何工作。

+ +

技术指标

+ + + + + + + + + + + + + + +
SpecificationStatusComment
{{SpecName('WebRTC 1.0', '#dom-rtcpeerconnection-createoffer', 'createOffer()')}}{{Spec2('WebRTC 1.0')}}Initial definition.
+ +

浏览器兼容性

+ +
+ + +

{{Compat("api.RTCPeerConnection.createOffer")}}

+
diff --git a/files/zh-cn/web/api/rtcpeerconnection/currentlocaldescription/index.html b/files/zh-cn/web/api/rtcpeerconnection/currentlocaldescription/index.html new file mode 100644 index 0000000000..651bb2801d --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/currentlocaldescription/index.html @@ -0,0 +1,80 @@ +--- +title: RTCPeerConnection.currentLocalDescription +slug: Web/API/RTCPeerConnection/currentLocalDescription +tags: + - API + - SDP + - WebRTC +translation_of: Web/API/RTCPeerConnection/currentLocalDescription +--- +

{{WebRTCSidebar}}

+ +

只读属性 RTCPeerConnection.currentLocalDescription 返回一个 {{domxref("RTCSessionDescription")}} 对象，该对象描述了 自上次 {{domxref("RTCPeerConnection")}} 完成协商与连接到远程端后，最近一次成功协商的连接的本地端。原文（describing the local end of the connection as it was most recently successfully negotiated since the last time the RTCPeerConnection finished negotiating and connecting to a remote peer）。也包括自RTCSessionDescription所代表的offer或anwser首次实例化以来，ICE代理可能已经生成的任何ICE候选人的列表。

+ +

若想改变 currentLocalDescription ，则调用 {{domxref("RTCPeerConnection.setLocalDescription()")}} 。这将会触发引发该值被设置的一系列事件。 如果希望详细了解策略与机制，查阅 {{SectionOnPage("/en-US/docs/Web/API/WebRTC_API/Connectivity", "Pending and current descriptions")}}。

+ +
+

与 {{domxref("RTCPeerConnection.localDescription")}} 不同， 这个值代表了当前连接的本地端的事实当前状态； localDescription 也许指明了一个当前正在切换中的连接的description。

+
+ +

语法

+ +
sessionDescription = RTCPeerConnection.currentLocalDescription;
+ +

返回值

+ +

连接本地端的当前description描述，如果成功设置了一个。否则返回null。

+ +

例子

+ +

本例子查看 currentLocalDescription 并且显示了包含 {{domxref("RTCSessionDescription")}} 对象的 type 与 sdp 字段的alert。

+ +
var pc = new RTCPeerConnection();
+…
+var sd = pc.currentLocalDescription;
+if (sd) {
+  alert("Local session: type='" +
+        sd.type + "'; sdp description='" +
+        sd.sdp + "'");
+}
+else {
+  alert("No local session yet.");
+}
+
+ +

参数类别

+ + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{ SpecName('WebRTC 1.0', '#dom-peerconnection-currentlocaldesc', 'RTCPeerConnection.currentLocalDescription') }}{{ Spec2('WebRTC 1.0') }}Initial specification.
+ +

浏览器兼容性

+ + + +

{{Compat("api.RTCPeerConnection.currentLocalDescription")}}

+ +
+

The addition of currentLocalDescription and {{domxref("RTCPeerConnection.pendingLocalDescription", "pendingLocalDescription")}} to the WebRTC spec is relatively recent. In browsers which don't support them, just use {{domxref("RTCPeerConnection.localDescription", "localDescription")}}.

+
+ +

参阅

+ + diff --git a/files/zh-cn/web/api/rtcpeerconnection/getdefaulticeservers/index.html b/files/zh-cn/web/api/rtcpeerconnection/getdefaulticeservers/index.html new file mode 100644 index 0000000000..96c8496248 --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/getdefaulticeservers/index.html @@ -0,0 +1,57 @@ +--- +title: RTCPeerConnection.getDefaultIceServers() +slug: Web/API/RTCPeerConnection/getDefaultIceServers +translation_of: Web/API/RTCPeerConnection/getDefaultIceServers +--- +

{{APIRef("WebRTC")}}{{SeeCompatTable}}

+ +

{{domxref("RTCPeerConnection")}} 接口的方法 getDefaultIceServers() 返回一个基于  {{domxref("RTCIceServer")}} 字典的对象数组。如果在 {{domxref("RTCPeerConnection")}} 的 {{domxref("RTCConfiguration")}} 中没有设置，该数组指向浏览器缺省使用的ICE servers，前提是浏览器确实存在缺省的ICE servers。然而，浏览器完全不必提供任何的缺省ICE Servers。

+ +

语法

+ +
 var defaultIceServers = RTCPeerConnection.getDefaultIceServers();
+ +

返回值

+ +

一个 ICE servers 的数组，以基于 {{domxref("RTCIceServer")}} 的对象组成，当没有在 {{domxref("RTCPeerConnection")}} 的设置中进行设置时，浏览器将使用它们。如果浏览器没有提供缺省值，将返回一个空数组，该属性的值永远不是 null。

+ +

例子

+ +
var pc = new RTCPeerConnection();
+var iceServers = pc.getDefaultIceServers();
+
+if (iceServers.length === 0) {
+  // Deal with the lack of default ICE servers, possibly by using our own defaults
+}
+ +

Specifications

+ + + + + + + + + + + + + + + + +
SpecificationStatusComment
WebRTC Extensions
+ +

Browser compatibility

+ + + +

{{Compat("api.RTCPeerConnection.getDefaultIceServers")}}

+ +

See also

+ + diff --git a/files/zh-cn/web/api/rtcpeerconnection/getreceivers/index.html b/files/zh-cn/web/api/rtcpeerconnection/getreceivers/index.html new file mode 100644 index 0000000000..4f59be48af --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/getreceivers/index.html @@ -0,0 +1,60 @@ +--- +title: RTCPeerConnection.getReceivers() +slug: Web/API/RTCPeerConnection/getReceivers +tags: + - Media + - RTCPeerConnection + - WebRTC + - getReceivers +translation_of: Web/API/RTCPeerConnection/getReceivers +--- +
{{APIRef("WebRTC")}}{{SeeCompatTable}}
+ +

RTCPeerConnection.getReceivers() 方法返回一个 {{domxref("RTCRtpReceiver")}} 对象的数组, 每个RTCRtpReceiver对象代表了一个RTP receiver。每个RTP receiver管理在一个 {{domxref("RTCPeerConnection")}} 上的 {{domxref("MediaStreamTrack")}} 的数据的接收与解码。

+ +

语法

+ +
var receivers = rtcPeerConnection.getReceivers();
+
+ +

返回值

+ +

一个 {{domxref("RTCRtpReceiver")}} 数组，一个对象就是连接上的一个轨道（track）。若连接上没有RTP receiver，则数组为空。

+ +

规范没有定义返回的RTCRtpReceiver实例的顺序，所以两次调用 getReceivers() 返回的顺序可能是不同的。

+ +

例子

+ +

待定

+ +

技术规范

+ + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{ SpecName('WebRTC 1.0', '#dom-peerconnection-getreceivers', 'RTCPeerConnection.getReceivers()') }}{{ Spec2('WebRTC 1.0') }}Initial specification.
+ +

浏览器兼容性

+ + + +

{{Compat("api.RTCPeerConnection.getReceivers")}}

+ +

参阅

+ + diff --git a/files/zh-cn/web/api/rtcpeerconnection/iceconnectionstate/index.html b/files/zh-cn/web/api/rtcpeerconnection/iceconnectionstate/index.html new file mode 100644 index 0000000000..ce202a7d8f --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/iceconnectionstate/index.html @@ -0,0 +1,110 @@ +--- +title: RTCPeerConnection.iceConnectionState +slug: Web/API/RTCPeerConnection/iceConnectionState +translation_of: Web/API/RTCPeerConnection/iceConnectionState +--- +

{{APIRef("WebRTC")}}{{SeeCompatTable}}

+ +

RTCPeerConnection.iceConnectionState 是一个只读属性，用于描述连接的ICE连接状态，返回值为枚举类型。

+ +

语法

+ +
 var state = peerConnection.iceConnectionState;
+ +

返回值

+ +

RTCIceConnectionState的返回值为下面列举中的一种:

+ + + +

例子

+ +
var pc = new RTCPeerConnection();
+var state = pc.iceConnectionState;
+ +

规范

+ + + + + + + + + + + + + + + + +
SpecificationStatusComment
{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-iceConnectionState', 'RTCPeerConnection.iceConnectionState') }}{{ Spec2('WebRTC 1.0') }}Initial specification.
+ +

浏览器兼容

+ +

{{ CompatibilityTable() }}

+ +
+ + + + + + + + + + + + + + + + + + + +
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{ CompatVersionUnknown() }} [1]{{ CompatVersionUnknown }} [1]{{ CompatNo() }}{{ CompatVersionUnknown() }}{{ CompatUnknown() }}
+
+ +
+ + + + + + + + + + + + + + + + + + + + + +
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatNo() }}{{ CompatUnknown() }}{{ CompatUnknown() }}
+
+ +

[1] Though this property is not prefixed, the interface it belongs to is.

+ +

参考文档

+ + diff --git a/files/zh-cn/web/api/rtcpeerconnection/icegatheringstate/index.html b/files/zh-cn/web/api/rtcpeerconnection/icegatheringstate/index.html new file mode 100644 index 0000000000..844c6d70e2 --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/icegatheringstate/index.html @@ -0,0 +1,57 @@ +--- +title: RTCPeerConnection.iceGatheringState +slug: Web/API/RTCPeerConnection/iceGatheringState +translation_of: Web/API/RTCPeerConnection/iceGatheringState +--- +

{{APIRef("WebRTC")}}{{SeeCompatTable}}

+ +

只读属性 RTCPeerConnection.iceGatheringState 返回一个描述连接的ICE收集状态的枚举值 RTCIceGatheringState。比如当ICE候选收集完成的时候，你可以通过该属性的变化侦测到。

+ +

通过监听 icegatheringstatechange 类型的事件，你可以侦测到该属性的变化。

+ +

语法

+ +
 var state = RTCPeerConnection.iceGatheringState;
+ +

值

+ +

可能的值是枚举类型 RTCIceGatheringState 的所有值。

+ +

{{page("/en-US/docs/Web/API/RTCPeerConnection", "RTCIceGatheringState enum", 0, 1)}}

+ +

例子

+ +
var pc = new RTCPeerConnection();
+var state = pc.iceGatheringState;
+ +

规格说明书

+ + + + + + + + + + + + + + + + +
规格状态说明
{{ SpecName('WebRTC 1.0', '#dom-peerconnection-ice-gathering-state', 'RTCPeerConnection.iceGatheringState') }}{{ Spec2('WebRTC 1.0') }}Initial specification.
+ +

浏览器兼容性说明

+ + + +

{{Compat("api.RTCPeerConnection.iceGatheringState")}}

+ +

See also

+ + diff --git a/files/zh-cn/web/api/rtcpeerconnection/index.html b/files/zh-cn/web/api/rtcpeerconnection/index.html new file mode 100644 index 0000000000..0bd2d71395 --- /dev/null +++ b/files/zh-cn/web/api/rtcpeerconnection/index.html @@ -0,0 +1,377 @@ +--- +title: RTCPeerConnection +slug: Web/API/RTCPeerConnection +tags: + - WebRTC + - 视频通话 +translation_of: Web/API/RTCPeerConnection +--- +

{{APIRef}}{{SeeCompatTable}}

+ +

RTCPeerConnection 接口代表一个由本地计算机到远端的WebRTC连接。该接口提供了创建，保持，监控，关闭连接的方法的实现。

+ +
+

提示: RTCPeerConnection 和RTCSessionDescription 是很多浏览器中使用的名称。强烈建议使用补充库，例如强大并且被广泛支持的Adapter.js，以确保您网站或Web应用程序的兼容性。值得注意的是Adapter.js不仅仅提供这些，它还做了一些其他补充以增强WebRTC在浏览器中的兼容性。参考：

+ +
var PeerConnection = window.RTCPeerConnection || window.mozRTCPeerConnection || window.webkitRTCPeerConnection;
+var SessionDescription = window.RTCSessionDescription || window.mozRTCSessionDescription || window.webkitRTCSessionDescription;
+var GET_USER_MEDIA = navigator.getUserMedia ? "getUserMedia" :
+                     navigator.mozGetUserMedia ? "mozGetUserMedia" :
+                     navigator.webkitGetUserMedia ? "webkitGetUserMedia" : "getUserMedia";
+var v = document.createElement("video");
+var SRC_OBJECT = 'srcObject' in v ? "srcObject" :
+                 'mozSrcObject' in v ? "mozSrcObject" :
+                 'webkitSrcObject' in v ? "webkitSrcObject" : "srcObject";
+
+ +

由于RTCPeerConnection实现了 {{domxref("EventTarget")}} 接口，故其可以接收处理事件。

+ +

构造函数

+ +
+
{{domxref("RTCPeerConnection.RTCPeerConnection()")}}
+
构造函数;创建一个新的RTCPeerConnection对象。
+
+ +

属性 

+ +

该接口的属性继承了其父接口, {{domxref("EventTarget")}}.

+ +
+
{{domxref("RTCPeerConnection.canTrickleIceCandidates")}} {{ReadOnlyInline}}
+
如果远端支持UDP打洞或支持通过中继服务器连接，则该属性值为true。否则，为false。该属性的值依赖于远端设置且仅在本地的 {{domxref("RTCPeerConnection.setRemoteDescription()")}}方法被调用时有效，如果该方法没被调用，则其值为null.
+
{{domxref("RTCPeerConnection.connectionState")}} {{ReadOnlyInline}}
+
只读connectionState属性通过返回由枚举RTCPeerConnectionState指定的字符串值之一来指示对等连接的当前状态。
+
{{domxref("RTCPeerConnection.currentLocalDescription")}} {{ReadOnlyInline}}
+
只读属性RTCPeerConnection.currentLocalDescription返回一个描述连接本地端的RTCSessionDescription对象，因为自上次RTCPeerConnection完成协商并连接到远程对等体之后，它最近成功协商。 还包括可能已经由ICE代理生成的任何ICE候选者的列表，因为首先被描述的描述所表示的要约或答案。
+
{{domxref("RTCPeerConnection.currentRemoteDescription")}} {{ReadOnlyInline}}
+
只读属性RTCPeerConnection.currentRemoteDescription返回一个RTCSessionDescription对象，描述连接的远程端，因为最近一次RTCPeerConnection完成协商并连接到远程对等体后最近成功协商。 还包括可能已经由ICE代理生成的任何ICE候选者的列表，因为首先被描述的描述所表示的要约或答案。
+
{{domxref("RTCPeerConnection.defaultIceServers")}} {{ReadOnlyInline}}
+
只读属性RTCPeerConnection.defaultIceServers根据RTCIceServer字典返回一个对象数组，该字典指示如果在RTCConfiguration中没有提供给RTCPeerConnection的默认情况下，浏览器将使用ICE服务器。 然而，浏览器根本不需要提供任何默认的ICE服务器。
+
{{domxref("RTCPeerConnection.iceConnectionState")}} {{ReadOnlyInline}}
+
只读属性RTCPeerConnection.iceConnectionState返回与RTCPeerConnection关联的ICE代理的状态类型为RTCIceConnectionState的枚举。
+
{{domxref("RTCPeerConnection.iceGatheringState")}} {{ReadOnlyInline}}
+
只读属性，返回一个RTCIceGatheringState类型的结构体，它描述了连接的ICE收集状态
+
{{domxref("RTCPeerConnection.idpLoginUrl")}} {{ReadOnlyInline}}
+
blah
+
{{domxref("RTCPeerConnection.localDescription")}} {{ReadOnlyInline}}
+
只读属性，返回一个 {{domxref("RTCSessionDescription")}} ，它描述了这条连接的本地端的会话控制（用户会话所需的属性以及配置信息）。如果本地的会话控制还没有被设置，它的值就会是null。
+
{{domxref("RTCPeerConnection.peerIdentity")}} {{ReadOnlyInline}}
+
只读属性，返回一个RTCIdentityAssertion,它由一组信息构成，包括一个域名（idp）以及一个名称（name），它们代表了这条连接的远端机器的身份识别信息。如果远端机器还没有被设置以及校验，这个属性会返回一个null值。一旦被设置，它不能被一般方法改变。
+
+ +

{{domxref("RTCPeerConnection.pendingLocalDescription")}} {{ReadOnlyInline}}

+ +
+
blah
+
{{domxref("RTCPeerConnection.pendingRemoteDescription")}} {{ReadOnlyInline}}
+
blah
+
{{domxref("RTCPeerConnection.remoteDescription")}} {{ReadOnlyInline}}
+
blah
+
{{domxref("RTCPeerConnection.sctp")}} {{ReadOnlyInline}}
+
blah
+
{{domxref("RTCPeerConnection.signalingState")}} {{ReadOnlyInline}}
+
+ +

返回一个RTC通信状态的结构体，这个结构体描述了本地连接的通信状态。这个 状态描述了一个定义连接配置的SDP offer。它包含了下列信息，与{{domxref("MediaStream")}} 类型本地相关的对象的描述，媒体流编码方式或RTP和  RTCP协议的选项 ，以及被ICE服务器收集到的candidates(连接候选者)。当{{domxref("RTCPeerConnection.signalingState")}}的值改变时，对象上的{{event("signalingstatechange")}}事件会被触发。

+ +

基本用法

+ +

一个基本的RTCPeerConnection使用需要协调本地机器以及远端机器的连接，它可以通过在两台机器间生成Session Description的数据交换协议来实现。呼叫方发送一个offer(请求)，被呼叫方发出一个answer（应答）来回答请求。双方-呼叫方以及被呼叫方，最开始的时候都要建立他们各自的RTCPeerConnection对象。

+ +
var pc = new RTCPeerConnection();
+pc.onaddstream = function(obj) {
+  var vid = document.createElement("video");
+  document.appendChild(vid);
+  vid.srcObject = obj.stream;
+}
+
+// Helper functions
+function endCall() {
+  var videos = document.getElementsByTagName("video");
+  for (var i = 0; i < videos.length; i++) {
+    videos[i].pause();
+  }
+
+  pc.close();
+}
+
+function error(err) { endCall(); }
+ +
+
呼叫初始化
+
+ +

如果你是呼叫方，你需要初始化一个连接

+ +
// Get a list of friends from a server
+// User selects a friend to start a peer connection with
+navigator.getUserMedia({video: true}, function(stream) {
+  pc.onaddstream({stream: stream});
+  // Adding a local stream won't trigger the onaddstream callback
+  pc.addStream(stream);
+
+  pc.createOffer(function(offer) {
+    pc.setLocalDescription(new RTCSessionDescription(offer), function() {
+      // send the offer to a server to be forwarded to the friend you're calling.
+    }, error);
+  }, error);
+})
+ +
+
呼叫回答
+
+ +

在另一端，你的朋友会从服务器收到offer信息。

+ +
var offer = getOfferFromFriend();
+navigator.getUserMedia({video: true}, function(stream) {
+  pc.onaddstream({stream: stream});
+  pc.addStream(stream);
+
+  pc.setRemoteDescription(new RTCSessionDescription(offer), function() {
+    pc.createAnswer(function(answer) {
+      pc.setLocalDescription(new RTCSessionDescription(answer), function() {
+        // send the answer to a server to be forwarded back to the caller (you)
+      }, error);
+    }, error);
+  }, error);
+})
+
+
+ +
+
处理应答
+
+ +

同时在呼叫发起方，你会收到这个应答（前面被呼叫方发出的answer），你需要将它设置为你的远端连接。

+ +
// pc was set up earlier when we made the original offer
+var offer = getResponseFromFriend();
+pc.setRemoteDescription(new RTCSessionDescription(offer), function() { }, error);
+
+ +

属性

+ +

这个接口从它的父元素中继承属性, {{domxref("EventTarget")}}.

+ +
+
{{domxref("RTCPeerConnection.iceConnectionState")}} {{ReadOnlyInline}}
+
返回一个RTCIceConnectionState类型的结构体，这个结构体描述了连接的ICE连接状态。当这个状态的值改变时，这个对象会触发一个{{event("iceconnectionstatechange")}} 事件。状态可能存在的值如下：
+
+
    +
  • "new": ICE服务器正在收集地址或正在等待远端的candidates(这两种情况可能同时存在)。
    • +
  • "checking": ICE服务器找到了远端的candidates（连接候选者）,这些candidates至少有一个，同时ICE服务器在检测这些candidates，尽管它可能还没有找到连接。此刻，ICE服务器可能仍在收集candidates（连接候选者）。
    • +
  • "connected": ICE服务器已经找到了一条可用的适合所有组件的连接，但它仍然在测试更多的远端candidate以提供更好的连接。同时，ICE服务器可能仍在收集candidates。
    • +
  • "completed": ICE服务器已经找到了一条可用的连接，并不再测试远端candidates。
    • +
  • "failed": ICE服务器已经检测了所有的远端candidates，但并没有找到可用的。对一些组件适用的连接可能已经被找到。
    • +
  • "disconnected": 至少一个组件的活跃度检查失败了，这可能是由糟糕的网络环境造成的一个短期状态，它可以被它自身所修复。
    • +
  • "closed": ICE服务器已经关闭，并不再响应请求。
    • +
+
+
{{domxref("RTCPeerConnection.iceGatheringState")}} {{ReadOnlyInline}}
+
返回一个iceGatheringState类型的结构体，它描述了这条连接的ICE收集状态。该状态可能取以下的值： +
    +
  • "new": 对象刚刚被创建,还没有网络化。
    • +
  • "gathering": ICE引擎正在为连接收集candidates(连接候选者)。
    • +
  • "complete": 引擎已经完成了candidates收集。但像添加一个新的接口或者一个新的turn服务器这些事件会导致状态回到"gathering"。
    • +
+
+
{{domxref("RTCPeerConnection.localDescription")}} {{ReadOnlyInline}}
+
返回一个 {{domxref("RTCSessionDescription")}} ，它描述了这条连接的本地端的会话控制（用户会话所需的属性以及配置信息）。如果本地的会话控制还没有被设置，它的值就会是null。
+
{{domxref("RTCPeerConnection.peerIdentity")}} {{ReadOnlyInline}}
+
返回一个RTCIdentityAssertion,它由一组信息构成，包括一个域名（idp）以及一个名称（name），它们代表了这条连接的远端机器的身份识别信息。如果远端机器还没有被设置以及校验，这个属性会返回一个null值。一旦被设置，它不能被一般方法改变。
+
{{domxref("RTCPeerConnection.remoteDescription")}} {{ReadOnlyInline}}
+
返回一个 {{domxref("RTCSessionDescription")}} 它描述了这条连接的远端机器的会话控制，如果远端机器还未被设置，它的值会是null。
+
{{domxref("RTCPeerConnection.signalingState")}} {{ReadOnlyInline}}
+
返回一个RTC通信状态的结构体，这个结构体描述了本地连接的通信状态。这个 状态描述了一个定义连接配置的SDP offer。它包含了下列信息，与{{domxref("MediaStream")}} 类型本地相关的对象的描述，媒体流编码方式或RTP和  RTCP协议的选项 ，以及被ICE服务器收集到的candidates(连接候选者)。当{{domxref("RTCPeerConnection.signalingState")}}的值改变时，对象上的{{event("signalingstatechange")}}事件会被触发。 它可能取下列的值： +
    +
  • "stable": 没有SDP offer/answer正在被交换，连接仍然处于初始化状态。
    • +
  • "have-local-offer": 这条连接的本地端机器已经本地应用了一个SDP offer。
    • +
  • "have-remote-offer": 这条连接的远端机器已经本地应用了一个SDP offer。
    • +
  • "have-local-pranswer": 一个来自远端的SDP offer已经被应用，同时一个SDP pranswer在本地被应用。
    • +
  • "have-remote-pranswer": 一个本地的SDP offer被应用，同时一个SDP pranswer在远端被应用。
    • +
  • "closed": 连接被关闭。
    • +
+
+
+ +

事件处理器

+ +
+
{{domxref("RTCPeerConnection.onaddstream")}}
+
是收到{{event("addstream")}} 事件时调用的事件处理器。 Such an event is 当{{domxref("MediaStream")}} 被远端机器添加到这条连接时，该事件会被触发。 当调用{{domxref("RTCPeerConnection.setRemoteDescription()")}}方法时，这个事件就会被立即触发，它不会等待SDP协商的结果。
+
{{domxref("RTCPeerConnection.ondatachannel")}}
+
是收到{{event("datachannel")}} 事件时调用的事件处理器。 当一个 {{domxref("RTCDataChannel")}} 被添加到连接时，这个事件被触发。
+
{{domxref("RTCPeerConnection.onicecandidate")}}
+
是收到 {{event("icecandidate")}} 事件时调用的事件处理器.。当一个 {{domxref("RTCICECandidate")}} 对象被添加时，这个事件被触发。
+
{{domxref("RTCPeerConnection.oniceconnectionstatechange")}}
+
是收到{{event("iceconnectionstatechange")}}事件时调用的事件处理器 。 当{{domxref("RTCPeerConnection.iceConnectionState", "iceConnectionState")}} 改变时，这个事件被触发。
+
{{domxref("RTCPeerConnection.onidentityresult")}}
+
是收到 {{event("identityresult")}}事件时调用的事件处理器。 当通过{{domxref("RTCPeerConnection.getIdentityAssertion()", "getIdentityAssertion()")}}生成身份断言, 或在生成一个answer或一个offer的过程中，这个事件被触发。
+
{{domxref("RTCPeerConnection.onidpassertionerror")}}
+
是收到 {{event("idpassertionerror")}} 事件时调用的事件处理器。当生成一个身份断言时，如果关联的身份提供者（idP）遇到一个错误，这个事件就会被触发。
+
{{domxref("RTCPeerConnection.onidpvalidationerror")}}
+
是收到 {{event("idpvalidationerror")}} 事件时调用的事件处理器。当检查 一个身份断言时，如果关联的身份提供者（idP）遇到一个错误，这个事件就会被触发。
+
{{domxref("RTCPeerConnection.onnegotiationneeded")}}
+
是收到{{event("negotiationneeded")}} 事件时调用的事件处理器， 浏览器发送该事件以告知在将来某一时刻需要协商。
+
{{domxref("RTCPeerConnection.onpeeridentity")}}
+
是收到{{event("peeridentity")}} 事件时调用的事件处理器, 当一条连接的peer identify被设置以及校验后，该事件被触发
+
{{domxref("RTCPeerConnection.onremovestream")}}
+
是收到{{event("removestream")}} 事件时调用的事件处理器，当一条{{domxref("MediaStream")}} 从连接上移除时，该事件被触发。
+
{{domxref("RTCPeerConnection.onsignalingstatechange")}}
+
是收到{{event("signalingstatechange")}} 事件时调用的事件处理器, 当{{domxref("RTCPeerConnection.signalingState", "signalingState")}}的值发生改变时，该事件被触发。
+
+ +

方法

+ +
+
{{domxref("RTCPeerConnection.RTCPeerConnection", "RTCPeerConnection()")}}
+
RTCPeerConnection的初始化函数，通过 new RTCPeerConnection()初始化一个RTCPeerConnection实例。
+
{{domxref("RTCPeerConnection.createOffer()")}}
+
生成一个offer，它是一个带有特定的配置信息寻找远端匹配机器（peer）的请求。这个方法的前两个参数分别是方法调用成功以及失败的回调函数，可选的第三个参数是用户对视频流以及音频流的定制选项（一个对象）。
+
{{domxref("RTCPeerConnection.createAnswer()")}}
+
在协调一条连接中的两端offer/answers时，根据从远端发来的offer生成一个answer。这个方法的前两个参数分别是方法调用成功以及失败时的回调函数，可选的第三个参数是生成的answer的可供选项。
+
{{domxref("RTCPeerConnection.setLocalDescription()")}}
+
改变与连接相关的本地描述。这个描述定义了连接的属性，例如：连接的编码方式。连接会受到它的改变的影响，而且连接必须能同时支持新的以及旧的描述。这个方法可以接收三个参数，一个{{domxref("RTCSessionDescription")}} 对象包含设置信息，还有两个回调函数，它们分别是方法调用成功以及失败的回调函数。
+
{{domxref("RTCPeerConnection.setRemoteDescription()")}}
+
改变与连接相关的远端描述。这个描述定义了连接的属性，例如：连接的编码方式。连接会受到它的改变的影响，而且连接必须能同时支持新的以及旧的描述。这个方法可以接收三个参数，一个{{domxref("RTCSessionDescription")}} 对象包含设置信息，还有两个回调函数，它们分别是方法调用成功以及失败的回调函数。
+
{{domxref("RTCPeerConnection.updateIce()")}}
+
更新ICE服务器时调用的方法。
+
{{domxref("RTCPeerConnection.addIceCandidate()")}}
+
添加iceCandidate时调用的方法。
+
{{domxref("RTCPeerConnection.getConfiguration()")}}
+
获取配置信息时调用的方法。
+
{{domxref("RTCPeerConnection.getLocalStreams()")}}
+
返回连接的本地媒体流数组。这个数组可能是空数组。
+
{{domxref("RTCPeerConnection.getRemoteStreams()")}}
+
返回连接的远端媒体流数组。这个数组可能是空数组。
+
{{domxref("RTCPeerConnection.getStreamById()")}}
+
返回连接中与所给id匹配的媒体流 {{domxref("MediaStream")}}，如果没有匹配项，返回null。
+
{{domxref("RTCPeerConnection.addStream()")}}
+
添加一个媒体流 {{domxref("MediaStream")}}作为本地音频或视频源。如果本地端与远端协调已经发生了，那么需要一个新的媒体流，这样远端才可以使用它。
+
{{domxref("RTCPeerConnection.removeStream()")}}
+
将一个作为本地音频或视频源的媒体流 {{domxref("MediaStream")}}移除。如果本地端与远端协调已经发生了，那么需要一个新的媒体流，这样远端才可以停止使用它。
+
{{domxref("RTCPeerConnection.close()")}}
+
关闭一个RTCPeerConnection实例所调用的方法。
+
{{domxref("RTCPeerConnection.createDataChannel()")}}
+
在一条连接上建立一个新的{{domxref("RTCDataChannel")}}（用于数据发送）。这个方法把一个数据对象作为参数，数据对象中包含必要的配置信息。
+
{{domxref("RTCPeerConnection.createDTMFSender()")}}
+
创建一个新的与特殊的{{domxref("MediaStreamTrack")}}相关的{{domxref("RTCDTMFSender")}}，可以在连接上发送{{Glossary("DTMF")}}手机信号。
+
{{domxref("RTCPeerConnection.getStats()")}}
+
生成一个新的{{domxref("RTCStatsReport")}}，它包含连接相关的统计信息。
+
{{domxref("RTCPeerConnection.setIdentityProvider()")}}
+
根据所给的三个参数设置身份提供者（IdP)，这三个参数是它的名称，通信所使用的协议（可选），以及一个可选的用户名。只有当一个断言被需要时，这个IdP才会被使用。
+
{{domxref("RTCPeerConnection.getIdentityAssertion()")}}
+
初始化身份断言的收集，只有当{{domxref("RTCPeerConnection.signalingState", "signalingState")}}的值不为"closed"时，它才有效。它自动完成，在需求发生前调用它是最好的选择。
+
+ +

构造函数

+ +
new RTCPeerConnection({{domxref("RTCConfiguration")}} configuration, optional {{domxref("MediaConstraints")}} constraints);
+ +
+

注意: PeerConnection需要传递一个RTCConfiguration对象作为参数，如果你没有传递参数的话，火狐浏览器会自动提供一个参数。

+
+ +

方法

+ +

createOffer

+ +

void createOffer({{domxref("RTCSessionDescriptionCallback")}} successCallback, {{domxref("RTCPeerConnectionErrorCallback")}} failureCallback, optional {{domxref("MediaConstraints")}} constraints);

+ +

createOffer方法会生成描述信息的一个blob对象，它会帮助连接到本地机器。当你已经找到一个远端的PeerConnection并且打算设置建立本地的PeerConnection时，你可以使用该方法。

+ +

举例

+ +
var pc = new PeerConnection();
+pc.addStream(video);
+pc.createOffer(function(desc){
+  pc.setLocalDescription(desc, function() {
+    // send the offer to a server that can negotiate with a remote client
+  });
+}
+ +

参数

+ +
+
successCallback（方法调用成功时的回调函数）
+
一个 {{domxref("RTCSessionDescriptionCallback")}} 它会收到一个 {{domxref("RTCSessionDescription")}} 对象作为参数。
+
errorCallback（方法调用失败时的回调函数）
+
一个 {{domxref("RTCPeerConnectionErrorCallback")}} 它会收到一个 {{domxref("DOMError")}} 对象作为参数。
+
[optional] constraints(可选的约束条件)
+
一个可选的{{domxref("MediaConstraints")}} 对象。
+
+ +

createAnswer

+ +

void createAnswer({{domxref("RTCSessionDescriptionCallback")}} successCallback, {{domxref("RTCPeerConnectionErrorCallback")}} failureCallback, optional {{domxref("MediaConstraints")}} constraints)")

+ +

对从远方收到的offer进行回答。

+ +

举例

+ +
var pc = new PeerConnection();
+pc.setRemoteDescription(new RTCSessionDescription(offer), function() {
+  pc.createAnswer(function(answer) {
+    pc.setLocalDescription(answer, function() {
+      // send the answer to the remote connection
+    })
+  })
+});
+ +

参数

+ +
+
successCallback（方法调用成功时的回调函数）
+
一个 {{domxref("RTCSessionDescriptionCallback")}} 它会收到一个 {{domxref("RTCSessionDescription")}} 对象作为参数。
+
errorCallback（方法调用失败时的回调函数）
+
一个 {{domxref("RTCPeerConnectionErrorCallback")}} 它会收到一个{{domxref("DOMError")}} 对象作为参数。
+
[optional] constraints（可选的约束条件）
+
+ +

      一个可选的{{domxref("MediaConstraints")}} 对象。

+ +

updateIce()

+ +

updateIce(optional {{domxref("RTCConfiguration")}} configuration, optional {{domxref("MediaConstraints")}} constraints)

+ +

该方法会更新ICE代理收集本地candidates以及连接云端candidates的进程。如果强制约束条件"IceTransports"存在，那么它会控制ICE代理的工作方式。它可以用于限制接听者对TURN candidates的使用，这样可以避免在请求被应答前泄露位置信息。如果这个方法影响了已经建立的连接，那么它可能导致ICE代理状态的改变以及媒体状态的改变。

+ +

举例

+ +

+
+
addIceCandidate()

+
+
addIceCandidate ({{domxref("RTCIceCandidate")}} candidate, {{domxref("Function")}} successCallback, {{domxref("RTCPeerConnectionErrorCallback")}} failureCallback);

+
+
除了被添加到远端描述之外，只要约束条件"IceTransports" 没有被设置为null，连接检测结果会被发送给新的candidates。如果这个方法影响了已经建立的连接，那么它可能导致ICE代理状态的改变以及媒体状态的改变。

+
+
举例

+
+
  pc.addIceCandidate(new RTCIceCandidate(candidate));
+

+
+
createDataChannel

+
+
{{domxref("RTCDataChannel")}} createDataChannel ({{domxref("DOMString")}} label, optional {{domxref("RTCDataChannelInit")}} dataChannelDict);

+
+
通过peerconnection建立一条数据信道，用于发送非视频音频信息。

+
+
例子

+
+
var pc = new PeerConnection();
+var channel = pc.createDataChannel("Mydata");
+channel.onopen = function(event) {
+  channel.send('sending a message');
+}
+channel.onmessage = function(event) { console.log(event.data); }

+
+
引申阅读

+
+
diff --git a/files/zh-cn/web/api/rtcpeerconnection/onaddstream/index.html b/files/zh-cn/web/api/rtcpeerconnection/onaddstream/index.html
new file mode 100644
index 0000000000..1c5a04d575
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/onaddstream/index.html
@@ -0,0 +1,103 @@
+---
+title: RTCPeerConnection.onaddstream
+slug: Web/API/RTCPeerConnection/onaddstream
+translation_of: Web/API/RTCPeerConnection/onaddstream
+---
+
{{APIRef("WebRTC")}}{{SeeCompatTable}}

+
+
当类型为{{domxref("MediaStreamEvent")}}的{{event("addstream")}} 事件发生时，通过{{domxref("RTCPeerConnection")}}触发RTCPeerConnection.onaddstream 事件处理函数。当远程媒体流{{domxref("MediaStream")}} 添加到连接后发送事件。当{{domxref("RTCPeerConnection.setRemoteDescription()")}} 后此事件立即被调用而不需要等待SDP交换完成。

+
+
语法

+
+
peerconnection.onaddstream = function;
+

+
+
值

+
+
+
+
例子

+
+
pc.onaddstream = function(ev) { alert("onaddstream event detected!"); };
+

+
+
规范

+
+
+ 
+  
+   
+   
+   
+  
+ 
+ 
+  
+   
+   
+   
+  
+ 
+
SpecificationStatusComment
{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-onaddstream', 'RTCPeerConnection.onaddstream') }}{{ Spec2('WebRTC 1.0') }}Initial specification.

+
+
浏览器兼容性

+
+
{{ CompatibilityTable() }}

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+  
+ 
+
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{ CompatVersionUnknown() }} [1]{{ CompatVersionUnknown }} [1]{{ CompatNo() }}{{ CompatVersionUnknown() }}{{ CompatUnknown() }}

+

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+   
+  
+ 
+
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatNo() }}{{ CompatUnknown() }}{{ CompatUnknown() }}

+

+
+
[1] Though this property is not prefixed, the interface it belongs to is.

+
+
扩展阅读

+
+
diff --git a/files/zh-cn/web/api/rtcpeerconnection/ondatachannel/index.html b/files/zh-cn/web/api/rtcpeerconnection/ondatachannel/index.html
new file mode 100644
index 0000000000..418f180f79
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/ondatachannel/index.html
@@ -0,0 +1,112 @@
+---
+title: RTCPeerConnection.ondatachannel
+slug: Web/API/RTCPeerConnection/ondatachannel
+translation_of: Web/API/RTCPeerConnection/ondatachannel
+---
+
{{APIRef("WebRTC")}}{{SeeCompatTable}}

+
+
RTCPeerConnection.ondatachannel 属性是一个{{domxref("EventHandler")}}，当这个{{event("datachannel")}}事件在{{domxref("RTCPeerConnection")}}发生时，它指定的那个事件处理函数就会被调用。这个事件继承于 {{domxref("RTCDataChannelEvent")}}，当远方伙伴调用{{domxref("RTCPeerConnection.createDataChannel", "createDataChannel()")}}时这个事件被加到这个连接（RTCPeerConnection）中。

+
+
在这个事件被收到的同时，这个{{domxref("RTCDataChannel")}} 实际上并没有打开，确保在open这个事件在RTCDataChannel触发以后才去使用它。

+
+
语法

+
+
RTCPeerConnection.ondatachannel = function;
+

+
+
值

+
+
将这个属性设置为接受一个参数的函数：这个参数是一个{{domxref("RTCDataChannelEvent")}}，它的channel属性是一个已经创建了的{{domxref("RTCDataChannel")}}对象

+
+
示例

+
+
pc.ondatachannel = function(ev) {
+  console.log('Data channel is created!');
+  ev.channel.onopen = function() {
+    console.log('Data channel is open and ready to be used.');
+  };
+};
+

+
+
规范

+
+
+ 
+  
+   
+   
+   
+  
+ 
+ 
+  
+   
+   
+   
+  
+ 
+
SpecificationStatusComment
{{ SpecName('WebRTC 1.0', '#dom-rtcpeerconnection-ondatachannel', 'RTCPeerConnection.ondatachannel') }}{{ Spec2('WebRTC 1.0') }}Initial specification.

+
+
浏览器支持

+
+
{{ CompatibilityTable}}

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+  
+ 
+
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{ CompatVersionUnknown}} [1]{{ CompatGeckoDesktop(18) }} [2]{{ CompatNo}}{{ CompatVersionUnknown}}{{ CompatUnknown}}

+

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+   
+  
+ 
+
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatUnknown}}{{ CompatUnknown}}{{ CompatGeckoMobile(22) }} [2]{{ CompatNo}}{{ CompatUnknown}}{{ CompatUnknown}}

+

+
+
[1] Though this property is not prefixed, the interface it belongs to is.

+
+
[2] This property's name isn't prefixed, but the interface it's in, {{domxref("RTCPeerConnection")}}, was prefixed as MozRTCPeerConnection until Firefox 44.

+
+
相关阅读

+
+
diff --git a/files/zh-cn/web/api/rtcpeerconnection/onicecandidate/index.html b/files/zh-cn/web/api/rtcpeerconnection/onicecandidate/index.html
new file mode 100644
index 0000000000..6389f53f6a
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/onicecandidate/index.html
@@ -0,0 +1,65 @@
+---
+title: RTCPeerConnection.onicecandidate
+slug: Web/API/RTCPeerConnection/onicecandidate
+translation_of: Web/API/RTCPeerConnection/onicecandidate
+---
+
{{APIRef("WebRTC")}}

+
+
 RTCPeerConnection 的属性 {{domxref("RTCPeerConnection.onicecandidate", "onicecandidate")}} （是一个事件触发器 {{domxref("EventHandler")}}） 能够让函数在事件{{event("icecandidate")}}发生在实例  {{domxref("RTCPeerConnection")}} 上时被调用。 只要本地代理{{Glossary("ICE")}} 需要通过信令服务器传递信息给其他对等端时就会触发。 这让本地代理与其他对等体相协商而浏览器本身在使用时无需知道任何详细的有关信令技术的细节，只需要简单地应用这种方法就可使用您选择的任何消息传递技术将ICE候选发送到远程对等方。

+
+
Syntax

+
+
rtcPeerConnection.onicecandidate = eventHandler;
+

+
+
Value

+
+
这应该设置为您提供的函数，该函数接受RTCPeerConnectionIceEvent表示icecandidate事件的对象作为输入。该功能应该通过信令服务器将可以在事件属性中找到其SDP的ICE候选者传递candidate给远程对等体。

+
+
如果事件的candidate属性是null，ICE收集已经完成。不应将此消息发送到远程对等方。发生这种情况时，连接iceGatheringState也已更改为complete。你不需要明确地注意这一点; 相反，如果你需要感知信令的结束，你应该注意一个icegatheringstatechange事件，表明ICE协商已经转变为complete状态。

+
+
Example

+
+
下面的示例基于文章信令和视频调用中的代码，为icecandidate事件设置处理程序，以便将候选项发送到远程对等方。

+
+
pc.onicecandidate = function(event) {
+  if (event.candidate) {
+    // Send the candidate to the remote peer
+  } else {
+    // All ICE candidates have been sent
+  }
+}

+
+
请注意，当检测到协议结束时{{domxref("RTCPeerConnectionIceEvent.candidate", "candidate")}} 属性为 null.

+
+
Specifications

+
+
+ 
+  
+   
+   
+   
+  
+ 
+ 
+  
+   
+   
+   
+  
+ 
+
SpecificationStatusComment
WebRTC 1.0：浏览器之间的实时通信

+    该规范中“RTCPeerConnection.onicecandidate”的定义。		{{ Spec2('WebRTC 1.0') }}Initial specification.

+
+
浏览器兼容性

+
+
+
+
{{Compat("api.RTCPeerConnection.onicecandidate")}}

+
+
See also

+
+
diff --git a/files/zh-cn/web/api/rtcpeerconnection/ontrack/index.html b/files/zh-cn/web/api/rtcpeerconnection/ontrack/index.html
new file mode 100644
index 0000000000..b92a83228c
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/ontrack/index.html
@@ -0,0 +1,106 @@
+---
+title: RTCPeerConnection.ontrack
+slug: Web/API/RTCPeerConnection/ontrack
+translation_of: Web/API/RTCPeerConnection/ontrack
+---
+
{{APIRef("WebRTC")}}{{SeeCompatTable}}RTCPeerConnection.ontrack 属性是一个 {{domxref("EventHandler")}} 此属性指定了在{{domxref("RTCPeerConnection")}}接口上触发 {{event("track")}} 事件时调用的方法。该方法接收一个{{domxref("RTCTrackEvent")}}类型的event对象，该event对象将在{{domxref("MediaStreamTrack")}}被创建时或者是关联到已被添加到接收集合的{{domxref("RTCRtpReceiver")}}对象中时被发送。

+
+
语法

+
+
RTCPeerConnection.ontrack = eventHandler;
+

+
+
参数

+
+
将ontrack设置为你提供的一个输入{{domxref("RTCTrackEvent")}}对象用于描述新的track将如何使用的方法。这一信息包含了代表新track的{{domxref("MediaStreamTrack")}}对象、{{domxref("RTCRtpReceiver")}}对象、{{domxref("RTCRtpTransceiver")}}对象以及一个{{domxref("MediaStream")}}对象列表，该对象列表表示该track是那个媒体流的一部分。

+
+
示例

+
+
本示例，从这篇文章的代码和视频调用的代码中，将传入的轨迹连接到将用于显示传入{{HTMLElement("video")}}元素。

+
+
pc.ontrack = function(event) {
+  document.getElementById("received_video").srcObject = event.streams[0];
+  document.getElementById("hangup-button").disabled = false;
+};
+

+
+
在第一行代码中，我们的ontrack 事件处理器获取传入的第媒体流数组中的第一个，并赋值给video元素的{{htmlattrxref("srcObject", "video")}} 。这样媒体流就和页面中的video元素结合起来以便于呈现给用户。第二行代码简单启用了“挂断”按钮，用户可以使用它去断开呼叫。

+
+
说明

+
+
+ 
+  
+   
+   
+   
+  
+ 
+ 
+  
+   
+   
+   
+  
+ 
+
说明状态注释
{{SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-ontrack', 'RTCPeerConnection.ontrack')}}{{Spec2('WebRTC 1.0')}}初始规范

+
+
各浏览器兼容性

+
+
{{CompatibilityTable}}

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+  
+ 
+
特性ChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{CompatNo}}{{CompatGeckoDesktop(46)}}[1]{{CompatNo}}{{CompatUnknown}}{{CompatUnknown}}

+

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+   
+  
+ 
+
FeatureAndroid WebviewChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{CompatNo}}{{CompatNo}}{{CompatGeckoDesktop(46)}}[1]{{CompatNo}}{{CompatUnknown}}{{CompatUnknown}}

+

+
+
[1] 在Firefox 45中引入了onaddtrack;在Firefox 46中重命名为ontrack

+
+
参见

+
+
diff --git a/files/zh-cn/web/api/rtcpeerconnection/peeridentity/index.html b/files/zh-cn/web/api/rtcpeerconnection/peeridentity/index.html
new file mode 100644
index 0000000000..b1565ae67c
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/peeridentity/index.html
@@ -0,0 +1,72 @@
+---
+title: RTCPeerConnection.peerIdentity
+slug: Web/API/RTCPeerConnection/peerIdentity
+translation_of: Web/API/RTCPeerConnection/peerIdentity
+---
+
{{APIRef("WebRTC")}}

+
+
只读属性 {{domxref("RTCPeerConnection")}}  peerIdentity ，返回{{jsxref("Promise")}} 对象，成功时返回 {{domxref("RTCIdentityAssertion")}} ，该结构 {{domxref("DOMString")}} 标识了远端的ID。这个身份标识在连接过程中将不会改变（直到连接结束）.

+
+
语法

+
+
 var identity = rtcPeerConnection.peerIdentity;

+
+
Value

+
+
A JavaScript {{jsxref("Promise")}} which resolves to an {{domxref("RTCIdentityAssertion")}} that describes the remote peer's identity.

+
+
当验证远程的身份ID出错时,  promise 将返回拒绝. 如果目标节点身份不存在, peerIdentity 将被设为 一个promise对象，并重启验证过程（一个断言）, 直到成功或者不再想继续。

+
+

+
注意: {{domxref("RTCPeerConnection.setRemoteDescription", "setRemoteDescription()")}} 返回的promise 将不会成功返回，除非目标节点身份信息可用。 如不可用，则setRemoteDescription() 将被拒绝. 若无目标节点ID, 就不不需要等setRemoteDescription() 这个返回验证成功了.

+

+
+
举个栗子

+
+
In this example, a function, getIdentityAssertion(), is created which asynchronously waits for the peer's identity to be verified, then returns the identity to the caller. If an error occurs and the promise is rejected, this logs the error to the console and returns null to the caller.

+
+
let pc = new RTCPeerConnection();
+
+/* ... */
+
+async function getIdentityAssertion(pc) {
+  try {
+    const identity = await pc.peerIdentity;
+    return identity;
+  } catch(err) {
+    console.log("Error identifying remote peer: ", err);
+    return null;
+  }
+}
+

+
+
Specifications

+
+
+ 
+  
+   
+   
+   
+  
+ 
+ 
+  
+   
+   
+   
+  
+ 
+
SpecificationStatusComment
{{ SpecName('WebRTC Identity', '#dom-rtcpeerconnection-peeridentity') }}{{ Spec2('WebRTC Identity') }}Initial specification.

+
+
Browser compatibility

+
+
+
+
{{Compat("api.RTCPeerConnection.peerIdentity")}}

+
+
See also

+
+
diff --git a/files/zh-cn/web/api/rtcpeerconnection/remotedescription/index.html b/files/zh-cn/web/api/rtcpeerconnection/remotedescription/index.html
new file mode 100644
index 0000000000..3c619163d6
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/remotedescription/index.html
@@ -0,0 +1,71 @@
+---
+title: RTCPeerConnection.remoteDescription
+slug: Web/API/RTCPeerConnection/remoteDescription
+tags:
+  - RTCPeerConnection
+  - WebRTC
+  - remoteDescription
+  - 中文
+translation_of: Web/API/RTCPeerConnection/remoteDescription
+---
+
{{APIRef("WebRTC")}}{{SeeCompatTable}}

+
+
只读属性 RTCPeerConnection.remoteDescription 返回一个 {{domxref("RTCSessionDescription")}} ，它描述了和远程对端之间的会话(包括配置和媒体信息) ，如果还没有被设置过的话，它会是 null.

+
+
这个值通常是通过信令服务器接收的对端的会话描述（作为提议或应答），调用{{domxref("RTCPeerConnection.setRemoteDescription()")}}之后生效。

+
+
语法

+
+
 var sessionDescription = peerConnection.remoteDescription;

+
+
从更基础的层面上看，如果该属性不为null，则返回值为{{domxref("RTCPeerConnection.pendingRemoteDescription")}}的值，否则，返回{{domxref("RTCPeerConnection.currentRemoteDescription")}}的值。有关此算法的详细信息及其使用原因，请参阅{{SectionOnPage("/en-US/docs/Web/API/WebRTC_API/Connectivity", "Pending and current descriptions")}}。

+
+
示例

+
+
此示例查看remoteDescription并显示包含{{domxref("RTCSessionDescription")}}对象的type和sdp字段的警告。

+
+
var pc = new RTCPeerConnection();
+…
+var sd = pc.remoteDescription;
+if (sd) {
+  alert("Remote session: type='" +
+        sd.type + "'; sdp description='" +
+        sd.sdp + "'");
+}
+else {
+  alert("No remote session yet.");
+}
+

+
+
规范

+
+
+ 
+  
+   
+   
+   
+  
+ 
+ 
+  
+   
+   
+   
+  
+ 
+
标准状态说明
{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-remoteDescription', 'RTCPeerConnection.remoteDescription') }}{{ Spec2('WebRTC 1.0') }}初始化规范

+
+
浏览器兼容性

+
+
+
+
{{Compat("api.RTCPeerConnection.remoteDescription")}}

+
+
相关链接

+
+
diff --git a/files/zh-cn/web/api/rtcpeerconnection/removestream/index.html b/files/zh-cn/web/api/rtcpeerconnection/removestream/index.html
new file mode 100644
index 0000000000..d8934b29c9
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/removestream/index.html
@@ -0,0 +1,118 @@
+---
+title: RTCPeerConnection.removeStream()
+slug: Web/API/RTCPeerConnection/removeStream
+translation_of: Web/API/RTCPeerConnection/removeStream
+---
+
{{APIRef("WebRTC")}}{{SeeCompatTable}}

+
+
RTCPeerConnection.removeStream() 方法用来移除本地音频或视频的 {{domxref("媒体流")}} 。 如果已经发生交互，远程主机可能需要使用一个新的媒体流。

+
+
当 {{domxref("RTCPeerConnection.signalingState", "signalingState")}} 的值为"closed"时，将抛出InvalidStateError异常。当  {{domxref("RTCPeerConnection.signalingState", "signalingState")}} 值为"stable"时， 将触发{{domxref("RTCPeerConnection")}}的 {{event("negotiationneeded")}} 事件。

+
+
语法

+
+
pc.removeStream(mediaStream);
+

+
+

+ 此方法没有返回值。
+

+
+
参数

+
+

+ 
mediaStream

+ 
是 {{domxref("MediaStream")}} 类型的表示要移除的媒体流

+

+
+
例子

+
+
var pc, videoStream;
+navigator.getUserMedia({video: true}, function(stream) {
+  pc = new RTCPeerConnection();
+  videoStream = stream;
+  pc.addStream(stream);
+}
+document.getElementById("closeButton").addEventListener("click", function(event) {
+  pc.removeStream(videoStream);
+  pc.close();
+}, false);

+
+
规范

+
+
+ 
+  
+   
+   
+   
+  
+ 
+ 
+  
+   
+   
+   
+  
+ 
+
SpecificationStatusComment
{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-removeStream-void-MediaStream-stream', 'RTCPeerConnection.removeStream()') }}{{ Spec2('WebRTC 1.0') }}Initial specification.

+
+
浏览器兼容性

+
+
{{ CompatibilityTable() }}

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+  
+ 
+
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{ CompatVersionUnknown() }} [1]{{ CompatVersionUnknown }} [1]{{ CompatNo() }}{{ CompatVersionUnknown() }}{{ CompatUnknown() }}

+

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+   
+  
+ 
+
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatNo() }}{{ CompatUnknown() }}{{ CompatUnknown() }}

+

+
+
[1] Though this property is not prefixed, the interface it belongs to is.

+
+
扩展阅读

+
+
diff --git a/files/zh-cn/web/api/rtcpeerconnection/rtcpeerconnection/index.html b/files/zh-cn/web/api/rtcpeerconnection/rtcpeerconnection/index.html
new file mode 100644
index 0000000000..70ebad3dd1
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/rtcpeerconnection/index.html
@@ -0,0 +1,131 @@
+---
+title: RTCPeerConnection()
+slug: Web/API/RTCPeerConnection/RTCPeerConnection
+translation_of: Web/API/RTCPeerConnection/RTCPeerConnection
+---
+
{{APIRef("WebRTC")}}{{SeeCompatTable}}

+
+
RTCPeerConnection()构造函数，返回一个新建的  {{domxref("RTCPeerConnection")}}实例，它代表了本地端机器与远端机器的一条连接。

+
+
语法

+
+
pc = new RTCPeerConnection([configuration]);

+
+
参数

+
+

+ 
configuration {{optional_inline}}

+ 
一个RTCConfiguration dictionary 提供了一条新建连接的可选参数。

+

+
+
RTCConfiguration dictionary

+
+
{{page("/en-US/docs/Web/API/RTCConfiguration", "Properties")}}

+
+
返回值

+
+
一个新生成的 {{domxref("RTCPeerConnection")}} 对象, 如果指定了配置信息，它按照指定配置进行配置，否则,它将按照基本配置进行配置。

+
+
Specifications

+
+
+ 
+  
+   
+   
+   
+  
+  
+   
+   
+   
+  
+ 
+
SpecificationStatusComment
{{SpecName('WebRTC 1.0', '#widl-ctor-RTCPeerConnection--RTCConfiguration-configuration', 'RTCPeerConnection()')}}{{Spec2('WebRTC 1.0')}}Initial definition.

+
+
浏览器支持性

+
+
{{CompatibilityTable}}

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+   
+  
+ 
+
特性ChromeEdgeFirefox (Gecko)Internet ExplorerOperaSafari (WebKit)
Basic support{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatGeckoDesktop(22)}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
iceCandidatePoolSize{{CompatChrome(59)}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}

+

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+   
+   
+   
+  
+ 
+
特性Android WebviewChrome for AndroidEdgeFirefox Mobile (Gecko)Firefox OSIE MobileOpera MobileSafari Mobile
Basic support{{CompatNo}}{{CompatVersionUnknown}}{{CompatVersionUnknown}}{{CompatGeckoMobile(24)}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}
iceCandiatePoolSize{{CompatNo}}{{CompatChrome(59)}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}{{CompatUnknown}}

+

+
+
引申阅读

+
+
diff --git a/files/zh-cn/web/api/rtcpeerconnection/setconfiguration/index.html b/files/zh-cn/web/api/rtcpeerconnection/setconfiguration/index.html
new file mode 100644
index 0000000000..a9e7df89bf
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/setconfiguration/index.html
@@ -0,0 +1,99 @@
+---
+title: RTCPeerConnection.setConfiguration()
+slug: Web/API/RTCPeerConnection/setConfiguration
+translation_of: Web/API/RTCPeerConnection/setConfiguration
+---
+
{{APIRef("WebRTC")}}{{SeeCompatTable}}

+
+
The RTCPeerConnection.setConfiguration() method sets the current configuration of the {{domxref("RTCPeerConnection")}} based on the values included in the specified {{domxref("RTCConfiguration")}} object. This lets you change the ICE servers used by the connection and which transport policies to use.

+
+
The most common use case for this method (and even then, probably not a very common use case) is to replace the set of ICE servers to be used. Two potential scenarios in which this might be done:

+
+
+
+

+
You cannot change the identity information for a connection once it's already been set.

+

+
+
语法

+
+
RTCPeerConnection.setConfiguration(configuration);

+
+
参数

+
+

+ 
configuration

+ 
{{domxref("RTCConfiguration")}}对象提供一些可以设置的选项。这些选项的改动不会附加到原来的设置，相反，新的选项会完全替代旧的选项。

+

+
+
异常

+
+

+ 
InvalidAccessError

+ 
One or more of the URLs specified in configuration.iceServers is a {{Glossary("TURN")}} server, but complete login information is not provided (that is, either the {{domxref("RTCIceServer.username")}} or {{domxref("RTCIceServer.credentials")}} is missing). This prevents successful login to the server.

+ 
InvalidModificationError

+ 
The configuration includes changed identity information, but the connection already has identity information specified. This happens if configuration.peerIdentity or configuration.certificates is set and their values differ from the current configuration.

+ 
InvalidStateError

+ 
{{domxref("RTCPeerConnection")}} 被关闭.

+ 
SyntaxError

+ 
configuration.iceServers 列表提供的一个或多个URL是无效的

+

+
+
Example

+
+
In this example, it has already been determined that ICE restart is needed, and that negotiation needs to be done using a different ICE server.

+
+
var restartConfig = { iceServers: [{
+                          urls: "turn:asia.myturnserver.net",
+                          username: "allie@oopcode.com",
+                          credential: "topsecretpassword"
+                      }]
+};
+
+myPeerConnection.setConfiguration(restartConfig);
+
+myPeerConnection.createOffer({"iceRestart": true}).then(function(offer) {
+  return myPeerConnection.setLocalDescription(offer);
+})
+.then(function() {
+  // send the offer to the other peer using the signaling server
+})
+.catch(reportError);

+
+
First, a new {{domxref("RTCConfiguration")}} is created, restartConfig, specifying the new ICE server and its credentials. This is then passed into setConfiguration(). ICE negotiation is restarted by calling {{domxref("RTCPeerConnection.createOffer()", "createOffer()")}}, specifying true as the value of the iceRestart option. From there, we handle the process as usual, by setting the local description to the returned offer and then sending that offer to the other peer.

+
+
Specifications

+
+
+ 
+  
+   
+   
+   
+  
+  
+   
+   
+   
+  
+ 
+
SpecificationStatusComment
{{SpecName('WebRTC 1.0', '#dom-rtcpeerconnection-setconfiguration', 'setConfiguration()')}}{{Spec2('WebRTC 1.0')}}Initial definition.

+
+
Browser compatibility

+
+

+
+
+
{{Compat("api.RTCPeerConnection.setConfiguration")}}

+

+
+
See also

+
+
diff --git a/files/zh-cn/web/api/rtcpeerconnection/setremotedescription/index.html b/files/zh-cn/web/api/rtcpeerconnection/setremotedescription/index.html
new file mode 100644
index 0000000000..9e8db040bc
--- /dev/null
+++ b/files/zh-cn/web/api/rtcpeerconnection/setremotedescription/index.html
@@ -0,0 +1,127 @@
+---
+title: RTCPeerConnection.setRemoteDescription()
+slug: Web/API/RTCPeerConnection/setRemoteDescription
+translation_of: Web/API/RTCPeerConnection/setRemoteDescription
+---
+
{{APIRef("WebRTC")}}{{SeeCompatTable}}

+
+
RTCPeerConnection.setRemoteDescription() 方法改变与连接相关的描述，该描述主要是描述有些关于连接的属性，例如对端使用的解码器。 连接受此更改影响，并且必须能够支持旧的和新的描述。 方法带三个参数，{{domxref("RTCSessionDescription")}} 对象用于设置，然后是更改成功的回调方法，一个是更改失败的回调方法。

+
+
方法是异步的，不用等待设置完成，成功会调用成功回调方法，失败则会调用错误回调方法。

+
+
连接的offer通常来自于负责匹配的服务器所发送的数据。执行者应调用此方法设置远程描述，然后生成发送到对端计算机的answer。

+
+
语法

+
+
aPromise = pc.setRemoteDescription(sessionDescription);
+
+pc.setRemoteDescription(sessionDescription, successCallback, errorCallback);
+

+
+
这个方法没有返回值。

+
+
参数

+
+

+ 
sessionDescription

+ 
Is a {{domxref("DOMString")}} is the description of the parameters to be applied to the remote session.

+ 
successCallback

+ 
Is a Function without parameter which will be called when the description has been successfully set. At this point, one can send the offer to a remote server that can forward it to a remote client

+ 
errorCallback

+ 
Is a RTCPeerConnectionErrorCallback which will be called if the description can't be set. It takes the following parameter:
+ 
    
+  
  • errorInformation which is a {{domxref("DOMString")}} describing the reason why the description has not been set.
    • 
+ 

+ 

+

+
+
Example

+
+
var pc = new PeerConnection();
+pc.setRemoteDescription( new RTCSessionDescription( offer ), function() {
+   pc.createAnswer( function( answer ) {
+     pc.setLocalDescription( answer, function() {
+       // send the answer to the remote connection
+    })
+  })
+});
+

+
+
Specifications

+
+
+ 
+  
+   
+   
+   
+  
+ 
+ 
+  
+   
+   
+   
+  
+ 
+
SpecificationStatusComment
{{ SpecName('WebRTC 1.0', '#widl-RTCPeerConnection-setRemoteDescription-void-RTCSessionDescription-description-VoidFunction-successCallback-RTCPeerConnectionErrorCallback-failureCallback', 'RTCPeerConnection.setRemoteDescription()') }}{{ Spec2('WebRTC 1.0') }}Initial specification.

+
+
Browser compatibility

+
+
{{ CompatibilityTable() }}

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+  
+ 
+
FeatureChromeFirefox (Gecko)Internet ExplorerOperaSafari
Basic support{{ CompatVersionUnknown() }} [1]{{ CompatVersionUnknown }} [1]{{ CompatNo() }}{{ CompatVersionUnknown() }}{{ CompatUnknown() }}

+

+
+

+
+ 
+  
+   
+   
+   
+   
+   
+   
+   
+  
+  
+   
+   
+   
+   
+   
+   
+   
+  
+ 
+
FeatureAndroidChrome for AndroidFirefox Mobile (Gecko)IE MobileOpera MobileSafari Mobile
Basic support{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatUnknown() }}{{ CompatNo() }}{{ CompatUnknown() }}{{ CompatUnknown() }}

+

+
+
[1] Though this property is not prefixed, the interface it belongs to is.

+
+
See also

+
+
-- 
cgit v1.2.3-54-g00ecf