PeerConnerction--中文翻译

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

注意: RTCPeerConnection 和  RTCSessionDescription在不同的浏览器中有不同的实现方式。（navigator.getUserMedia() 方法也是如此）如果有必要，则需要考虑在不同浏览器的实现。例如: 

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";

这将提高您的这将提高您的网站或网络应用的兼容性。 Adapter.js 提供的代码解决了浏览器兼容性的问题 

由于RTCPeerConnection实现了 EventTarget 接口，故其可以接收处理事件。

构造函数

RTCPeerConnection.RTCPeerConnection()

构造函数;创建一个新的RTCPeerConnection对象。

属性 

该接口的属性继承了其父接口, EventTarget.

RTCPeerConnection.canTrickleIceCandidates 只读

如果远端支持UDP打洞或支持通过中继服务器连接，则该属性值为true。否则，为false。该属性的值依赖于远端设置且仅在本地的 RTCPeerConnection.setRemoteDescription()方法被调用时有效，如果该方法没被调用，则其值为null.

RTCPeerConnection.connectionState 只读

只读connectionState属性通过返回由枚举RTCPeerConnectionState指定的字符串值之一来指示对等连接的当前状态。

RTCPeerConnection.currentLocalDescription 只读

只读属性RTCPeerConnection.currentLocalDescription返回一个描述连接本地端的RTCSessionDescription对象，因为自上次RTCPeerConnection完成协商并连接到远程对等体之后，它最近成功协商。 还包括可能已经由ICE代理生成的任何ICE候选者的列表，因为首先被描述的描述所表示的要约或答案。

RTCPeerConnection.currentRemoteDescription 只读

只读属性RTCPeerConnection.currentRemoteDescription返回一个RTCSessionDescription对象，描述连接的远程端，因为最近一次RTCPeerConnection完成协商并连接到远程对等体后最近成功协商。 还包括可能已经由ICE代理生成的任何ICE候选者的列表，因为首先被描述的描述所表示的要约或答案。

RTCPeerConnection.defaultIceServers 只读

只读属性RTCPeerConnection.defaultIceServers根据RTCIceServer字典返回一个对象数组，该字典指示如果在RTCConfiguration中没有提供给RTCPeerConnection的默认情况下，浏览器将使用ICE服务器。 然而，浏览器根本不需要提供任何默认的ICE服务器。

RTCPeerConnection.iceConnectionState 只读

只读属性RTCPeerConnection.iceConnectionState返回与RTCPeerConnection关联的ICE代理的状态类型为RTCIceConnectionState的枚举。

RTCPeerConnection.iceGatheringState 只读

返回一个类型为RTCIceGatheringState的枚举，该枚举描述了连接的ICE收集状态。

RTCPeerConnection.idpLoginUrl 

RTCPeerConnection.localDescription 只读

返回描述连接本地端的会话的RTCSessionDescription。如果尚未设置，则可以为null。

RTCPeerConnection.peerIdentity 只读

返回一个RTCIdentityAssertion，它是一个域名（idp）和一个名称（name），表示此连接的远程对等体的身份，一旦设置和验证。如果没有对等体尚未设置和验证，则此属性将返回null。一旦设定，通过适当的方法，它不能改变。

RTCPeerConnection.pendingLocalDescription 只读

RTCPeerConnection.pendingRemoteDescription 只读

blah

RTCPeerConnection.remoteDescription 只读

blah

RTCPeerConnection.sctp 只读

blah

RTCPeerConnection.signalingState 只读

返回一个类型为RTCSignalingState的枚举，描述本地连接的信令状态。该状态描述了定义连接配置的SDP报价;这包括包括MediaStream类型的本地关联对象的描述，编解码器/ RTP / RTCP选项以及由ICE代理收集的候选者的信息。当此值更改时，会在该对象上触发一个signalstatechange事件。

 

基本用法

 

基本的RTCPeerConnection使用包括通过生成会话描述协议在两者之间交换来协商本地计算机和远程本地计算机之间的连接。即来电者发送报价。被叫方回答。双方，主叫方和被叫方都需要最初建立自己的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);

}
接听电话

在另一端，朋友将从服务器收到报价。

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);

}

处理答案

在原始机器上，您将收到响应，并将其设置为远程连接

// pc was set up earlier when we made the original offer

var offer = getResponseFromFriend();

pc.setRemoteDescription(new RTCSessionDescription(offer), function() { }, error);

 

属性编辑

此接口从其父元素EventTarget继承属性。

 

RTCPeerConnection.iceConnectionState只读

返回一个类型为RTCIceConnectionState的枚举，该枚举描述连接的ICE连接状态。当此值更改时，对象上将触发iceconnectionstatechange事件。可能的值是：

“"new"”：ICE代理正在收集地址或等待远程候选人（或两者）。

“checking”：ICE代理有至少一个组件的远程候选，并且检查它们，尽管它尚未找到连接。同时，它仍然可能在收集候选人。

“connected”：ICE代理已经为每个组件找到可用的连接，但仍然在测试更多的远程候选人以获得更好的连接。同时，它仍然可能在收集候选人。

“completed”：ICE代理已经为每个组件找到可用的连接，并且不再是测试远程候选人。

“failed”：ICE代理检查了所有远程候选人，并没有找到至少一个组件的匹配项。某些组件可能已找到连接。

“disconnected”：活动检查至少有一个组件失败。这可能是一个暂时的状态， G。在一个片状网络上，可以自行恢复。

“closed”：ICE代理已关闭，并没有回答请求。

RTCPeerConnection.iceGatheringState只读

返回一个类型为RTCIceGatheringState的枚举，该枚举描述了连接的ICE收集状态。可能的值是：

 “new”：对象刚刚创建，没有发生网络。

“complete”：ICE引擎正在收集候选人进行此连接。 “完成”：ICE引擎已经完成了收集。诸如添加新界面或新的TURN服务器等事件将导致状态返回收集。

RTCPeerConnection.localDescription只读

返回描述连接本地端的会话的RTCSessionDescription。如果尚未设置，则可以为null。

RTCPeerConnection.peerIdentity只读

返回一个RTCIdentityAssertion，它是一个域名（idp）和一个名称（name），表示此连接的远程对等体的身份，一旦设置和验证。如果没有对等体尚未设置和验证，则此属性将返回null。一旦设定，通过适当的方法，它不能改变。

RTCPeerConnection.remoteDescription只读

返回描述连接远程端的会话的RTCSessionDescription。如果尚未设置，则可以为null。

RTCPeerConnection.signalingState只读

返回一个类型为RTCSignalingState的枚举，描述本地连接的信令状态。该状态描述了定义连接配置的SDP报价，如MediaStream类型的本地关联对象的描述，编解码器/ RTP / RTCP选项，由ICE代理收集的候选者。当此值更改时，会在该对象上触发一个signalstatechange事件。可能的值是：

“stable”：没有SDP报价/答复交换进行中。这也是连接的初始状态。

“have-local-offer”：本地连接本地本地应用SDP优惠。

“have-remote-offer”：连接的远端本地应用了SDP报价。

“have-local-pranswer”：远程SDP报价已被应用，SDP转移应用于本地。

“have-remote-pranswer”：本地SDP报价已被应用，并且远程应用SDP报文。

“closed”：连接已关闭。

 

事件处理程序

 

RTCPeerConnection.onaddstream

当接收到addstream事件时调用事件处理程序。当远程对等体将MediaStream添加到此连接时，会发送此类事件。事件在调用RTCPeerConnection.setRemoteDescription（）之后立即发送，并且不等待SDP协商的结果。

RTCPeerConnection.ondatachannel

当接收到datachannel事件时调用事件处理程序。当向此连接添加RTCDataChannel时，会发送此类事件。

RTCPeerConnection.onicecandidate

当接收到icecandidate事件时调用事件处理程序。当RTCICECandidate对象添加到脚本时，会发送此类事件。

RTCPeerConnection.oniceconnectionstatechange

当接收到iceconnectionstatechange事件时调用事件处理程序。当iceConnectionState的值发生变化时，会发送这样的事件。

RTCPeerConnection.onidentityresult

当接收到identityresult事件时调用事件处理程序。当通过getIdentityAssertion（）生成身份断言，或在创建提议或答案时，发送这样的事件。

RTCPeerConnection.onidpassertionerror

当接收到idpassertionerror事件时调用事件处理程序。当相关联的身份提供者（IdP）在产生身份断言时遇到错误时发送这样的事件。

RTCPeerConnection.onidpvalidationerror

当接收到idpvalidationerror事件时，事件处理程序是否完成。当相关联的身份提供者（IdP）在验证身份断言时遇到错误时发送这样的事件。

RTCPeerConnection.onnegotiationneeded

是在接收到由浏览器发送的协商请求事件来调用事件处理程序以通知在将来的某个时刻进行协商的事件处理程序。

RTCPeerConnection.onpeeridentity

当接收到在此连接上设置和验证对等体标识时发送的同级事件时调用事件处理程序。

RTCPeerConnection.onremovestream

当从该连接中删除MediaStream时发送的removestream事件被接收时，调用事件处理程序。

RTCPeerConnection.onsignalingstatechange

当signalStatechange事件，当signalState的值发生变化时，调用事件处理程序。

方法

RTCPeerConnection（）

 

RTCPeerConnection.createOffer（）

创建一个请求以查找具有特定配置的远程对等体的请求。该方法的两个第一参数分别是成功和错误回调，可选的第三个参数是用户想要的选项，如音频或视频流。

RTCPeerConnection.createAnswer（）

创建对远程对等体收到的报价的回答，以两部分提供/回答协商连接。两个第一个参数分别是成功和错误回调，可选的第三个参数代表要创建的答案的选项。

RTCPeerConnection.setLocalDescription（）

更改与连接相关联的本地描述。该描述定义连接的属性，如其编解码器。连接受此更改的影响，并且必须能够支持旧的和新的描述。该方法需要三个参数，一个RTCSessionDescription对象进行设置，两个回调，一个调用的描述成功，另一个调用失败。

RTCPeerConnection.setRemoteDescription（）

更改与连接关联的远程描述。该描述定义连接的属性，如其编解码器。连接受此更改的影响，并且必须能够支持旧的和新的描述。该方法需要三个参数，一个RTCSessionDescription对象进行设置，两个回调，一个调用的描述成功，另一个调用失败。

RTCPeerConnection.updateIce（）

 

RTCPeerConnection.addIceCandidate（）

 

RTCPeerConnection.getConfiguration（）

 

RTCPeerConnection.getLocalStreams（）

返回与连接的本地端相关联的MediaStream数组。数组可能为空。

RTCPeerConnection.getRemoteStreams（）

返回与连接的远程端相关联的MediaStream数组。数组可能为空。

RTCPeerConnection.getStreamById（）

返回具有与连接的本地或远程端相关联的给定ID的MediaStream。如果没有流匹配，则返回null。

RTCPeerConnection.addStream（）

添加MediaStream作为本地音频或视频源。如果谈判已经发生，则需要一个新的远程对等体才能使用它。

RTCPeerConnection.removeStream（）

删除MediaStream作为本地音频或视频源。如果谈判已经发生，则需要一个新的远程对等体停止使用它。

RTCPeerConnection.close（）

突然关闭连接。

RTCPeerConnection.createDataChannel（）

创建与此连接相关联的新RTCDataChannel。该方法使用字典作为参数，底层数据通道需要配置，如其可靠性。

RTCPeerConnection.createDTMFSender（）

创建一个新的RTCDTMFSender，与特定的MediaStreamTrack相关联，可以通过连接发送DTMF电话信令。

RTCPeerConnection.getStats（）

创建一个新的RTCStatsReport，它包含并允许访问有关连接的统计信息。 RTCPeerConnection.setIdentityProvider（）

将身份提供者（IdP）设置为参数中给出的三元组：其名称，用于与之通信的协议（可选）和可选的用户名。只有当需要断言时，才会使用IdP。 RTCPeerConnection.getIdentityAssertion（）

启动身份断言的收集。这只有在signalState不是“关闭”时才有效果。处理RTCPeerConnection的应用程序不会期望：这是自动完成的;明确的通话只允许预测需要。

构造函数

new RTCPeerConnection(RTCConfiguration configuration, optional MediaConstraints constraints);

注意：虽然PeerConnection规范读取像传递一个RTCConfiguration对象是必需的，但如果没有，则Firefox将提供默认值。

方法

createOffer

 

void createOffer（RTCSessionDescriptionCallback  successCallback，RTCPeerConnectionErrorCallback  failureCallback，可选MediaConstraints约束）;

 

创建报价生成一个描述数据块，以方便与本地机器的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

将传递一个RTCSessionDescription对象的RTCSessionDescriptionCallback errorCallback
一个RTCPeerConnectionErrorCallback将传递一个单一的DOMError对象

[optional] constraints

       MediaConstraints对象可选。

createAnswer

               void createAnswer（RTCSessionDescriptionCallback successCallback，RTCPeerConnectionErrorCallback failureCallback，可选MediaConstraints约束）“）

               响应从远程连接发送的优惠。

例

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

将传递一个RTCSessionDescription对象的RTCSessionDescriptionCallback errorCallback

一个RTCPeerConnectionErrorCallback将传递一个单一的DOMError对象

[optional] constraints

MediaConstraints对象可选。

updateIce（）

 

updateIce(optional RTCConfiguration configuration,optional MediaConstraints constraints)

updateIce方法更新收集当地候选人和ping远程候选人的ICE代理进程。如果有一个称为“IceTransports”的强制约束，它将控制ICE引擎如何行动。这可以用来限制被叫方对TURN候选人的使用，以避免在接受呼叫之前泄露位置信息。该呼叫可能导致ICE代理的状态发生变化，并且如果导致建立连接，则可能导致媒体状态的改变。

addIceCandidate()

addIceCandidate (RTCIceCandidate candidate, Function successCallback, RTCPeerConnectionErrorCallback failureCallback);

addIceCandidate（）方法为ICE代理提供了一个远程候选。除了添加到远程描述之外，只要“IceTransports”约束未设置为“none”，连接检查将被发送到新的候选。此呼叫将导致ICE代理的连接状态发生更改，如果导致不同的连接建立，可能会导致媒体状态的更改。

例子

pc.addIceCandidate(new RTCIceCandidate(candidate));

createDataChannel

RTCDataChannel createDataChannel (DOMString label, optional RTCDataChannelInitdataChannelDict);

创建用于通过对等连接发送非视频或音频数据的数据通道

Example

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); }