开发学院

您的位置:首页>教程>正文

教程正文

WebRTC RTCPeerConnection接口

WebRTC RTCPeerConnection对象接口


RTCPeerConnection API是每个浏览器之间点对点连接的核心。要创建RTCPeerConnection对象,只需编写:


var pc = RTCPeerConnection(config);


config配置参数中至少包含iceServers参数。它是包含有关STUN和TURN服务器的信息的URL对象数组,在查找ICE候选时使用。您可以在code.google.com找到可用的公共STUN服务器的列表。


根据您是发起者还是被发起对象,在连接的每一边使用稍微不同的方式使用RtcPeerConnection对象。



下面是用户流程:


注册onicecandidate处理程序,它将任何ICE候选发送给其他对等方。


注册onaddstream处理程序,它负责处理从远程计算机接收到的视频流的显示。


注册消息处理程序。您的信令服务器还应该有一个处理来自远程计算机的消息处理程序。如果消息包含RTCSessionDescription对象,则应该使用RTCSessionDescription()方法将其添加到RTCPeerConnection对象。如果消息包含RTCIceCandidate对象,则应该使用addIceCandidate()方法将其添加到RTCPeerConnection对象。


使用getUserMedia()设置本地媒体流,并使用addstream()方法将其添加到RTCPeerConnection对象。


开始提供/回答协商过程,这是呼叫者的流量不同于被呼叫者的唯一步骤。调用者使用createoffer( )方法开始协商,并注册一个收到rtcsessiondescription对象的回调。然后,这个回调应该使用setlocaldescription( )将这个rtcsessiondescription对象添加到rtcpeerconnection对象中。最后,调用者应该使用信令服务器将这个rtcsessiondescription发送到远程计算机。另一方面,被呼叫者,在createanswer()方法中注册相同的回调。请注意,只有在从调用者收到通知后,才会启动流。


RTCPeerConnection API说明


属性列表


RTCPeerConnection.iceConnectionState (只读):返回描述连接状态的RTCIceConnectionState枚举。当此值更改时,将触发IceConnectionStateChange事件。'

取值范围

new-ICE代理正在等待远程候选或收集地址。

checking-ICE代理有远程候选,正在检查可用连接。

connected-ICE代理找到了可用的连接,但仍在检查更多的候选以获得更好的连接。

completed-ICE代理找到一个可用的连接,并停止测试远程候选。

failed-ICE代理没有找到可以匹配的链接。

disconnected-ICE代理已经断开链接。

closed-ICE代理已经关闭链接。


RTCPeerConnection.iceGatheringState (只读):返回描述连接的ICE状态的RTCIceGatheringState枚举。

new - 对象被创建

gathering -ICE正在收集候选

complete - ICE已完成收集


RTCPeerConnection.localDescription (只读):返回描述本地会话的RTCSessionDescription。如果尚未设置,则可以为空。


RTCPeerConnection.peerIdentity (只读):返回一个RTCIdentityAssertion。它由国内流离失所者(域名)和表示远程对等项身份的名称组成。



RTCPeerConnection.remoteDescription (只读):返回描述远程会话的RTCSessionDescription 。如果尚未设置,则可以为空。


RTCPeerConnection.signalingState (只读):返回描述本地连接的信令状态的RTCSignalingState枚举。这个状态描述了SDP的提供。当此值更改时,将触发signalingstatechange事件。

取值范围:

stable - 初始状态。在进度中没有SDP提议/应答交换。

have-local-offer - 连接的本地端本地使用SDP提议。

have-remote-offer - 连接的远程端本地使用SDP提议。

have-local-pranswer - 已接受远程SDP提议,且一个SDPpranswer在本地应用

have-remote-pranswer - 已应用本地SDP,且远程也已应用SDPpranswer。

closed  - 链接断开


事件处理


RTCPeerConnection.onaddstream:在触发addstream事件时调用此处理程序。当远程计算机加入到此连接时,将发送此事件。

RTCPeerConnection.ondatachannel:在触发datachannel事件时调用此处理程序。当将rtcdatachannel添加到此连接时,将发送此事件。

RTCPeerConnection.onicecandidate:在触发icecandidate事件时调用此处理程序。当将rtcicecandidate对象添加到脚本时,将发送此事件。

RTCPeerConnection.oniceconnectionstatechange:在触发iceconnectionstatechange事件时调用此处理程序。当iceconnectionstate更改的值时,将发送此事件。

RTCPeerConnection.onidentityresult:在触发identityresult事件时调用此处理程序。当在创建报价或通过getidentityassertion( )的应答期间生成身份断言时,将发送此事件。

RTCPeerConnection.onidpassertionerror:在触发idpassertionerror事件时调用此处理程序。当国内流离失所者(identitry提供程序)在生成身份断言时发现错误时,将发送此事件。

RTCPeerConnection.onidpvalidation:在触发idpvalidationerror事件时调用此处理程序。当国内流离失所者(identitry提供程序)在验证身份断言时发现错误时发送此事件。

RTCPeerConnection.onnegotiationneeded:在触发negotiationneeded事件时调用此处理程序。此事件由浏览器发送以通知协商,在将来的某个时间将需要协商。

RTCPeerConnection.onpeeridentity:在触发peeridentity事件时调用此处理程序。当在此连接上设置和验证对等身份时,将发送此事件。

RTCPeerConnection.onremovestream:在触发signalingstatechange事件时调用此处理程序。当signalingstate更改的值时,将发送此事件。

RTCPeerConnection.onsignalingstatechange:在触发removestream事件时调用此处理程序。当从此连接中删除mediastream时,将发送此事件。



方法说明


RTCPeerConnection():返回一个新的RTCPeerConnection对象.

RTCPeerConnection.createOffer():创建一个提议(请求)来查找远程节点,方法的前两个参数是成功和错误的回调,第三个参数是可选项,例如是否启用音频或视频流。

RTCPeerConnection.createAnswer():提议/应答的协商过程中创建对远程节点收到提议的答复,方法的前两个参数是成功和错误回调,第三个参数是要创建的答案的可选项。

RTCPeerConnection.setLocalDescription():更改本地的连接描述,描述定义连接的属性。连接必须能够支持新的和旧的描述。方法有三个参数,即:RTCSessionDescription对象,更改成功的回调,更改失败的回调。

RTCPeerConnection.setRemoteDescription():更改远端的连接描述,描述定义连接的属性。连接必须能够支持新的和旧的描述。方法有三个参数,即:RTCSessionDescription对象,更改成功的回调,更改失败的回调。

RTCPeerConnection.updateIce():更新ICE代理的状态

RTCPeerConnection.addIceCandidate():为ICE代理提供远程候选。

RTCPeerConnection.getConfiguration():返回一个RTCConfiguration对象,它表示RTCPeerConnection对象的配置。

RTCPeerConnection.getLocalStreams():返回本地MediaStream连接的数组。

RTCPeerConnection.getRemoteStreams():返回远程MediaStream连接的数组。

RTCPeerConnection.getStreamById():返回指定id的本地或远程MediaStream。

RTCPeerConnection.addStream():添加一个MediaStream作为本地视频或音频源。

RTCPeerConnection.removeStream():移除作为本地视频或音频源的MediaStream。

RTCPeerConnection.close():关闭一个链接。

RTCPeerConnection.createDataChannel():创建一个新的RTCDataChannel。

RTCPeerConnection.createDTMFSender():创建与特定MediaStreamTrack关联的新rtcdtmfsender。允许通过连接发送DTMF(双音多频)电话信令.

RTCPeerConnection.getStats():创建包含连接的统计信息的新RTCStatsReport。

RTCPeerConnection.setIdentityProvider():设置身份提供者,获取三个参数—名称、用于通信的协议和可选的用户名。

RTCPeerConnection.getIdentityAssertion():收集身份断言,预期在应用程序中不会处理此方法。因此,您可以显式地调用它来预测需求。


建立连接


现在让我们创建一个例子程序,首先,运行在"信号服务器"章节使用node serer开发的信号服务器.


创建index.html文件并添加以下代码:

<html>    
<head>       
<meta charset="utf-8"/>    
</head>   
<body>       
<div>          
<input type ="text" id = "loginInput" />          
<button id = "loginBtn">Login</button>       
</div>       
<div>          
<input type = "text" id = "otherUsernameInput" />         
<button id = "connectToOtherUsernameBtn">Establish connection</button>       
</div>       
<script src = "client2.js"></script>   
</body>
</html>



您可以看到,我们已经添加了用于登录的文本输入框、登录按钮、用于跟其他用户交互的文本输入框以及连接按钮。现在创建一个client.js文件,并添加以下代码:

//setup a peer connection with another user 
connectToOtherUsernameBtn.addEventListener("click", function () { 
 
   var otherUsername = otherUsernameInput.value; 
   connectedUser = otherUsername;
	
   if (otherUsername.length > 0) { 
      //make an offer 
      myConnection.createOffer(function (offer) { 
         console.log(); 
         send({ 
            type: "offer", 
            offer: offer 
         });
			
         myConnection.setLocalDescription(offer); 
      }, function (error) { 
         alert("An error has occurred."); 
      }); 
   } 
}); 
 
//when somebody wants to call us 
function onOffer(offer, name) { 
   connectedUser = name; 
   myConnection.setRemoteDescription(new RTCSessionDescription(offer)); 
	
   myConnection.createAnswer(function (answer) { 
      myConnection.setLocalDescription(answer); 
		
      send({ 
         type: "answer", 
         answer: answer 
      }); 
		
   }, function (error) { 
      alert("oops...error"); 
   }); 
}
  
//when another user answers to our offer 
function onAnswer(answer) { 
   myConnection.setRemoteDescription(new RTCSessionDescription(answer)); 
} 
 
//when we got ice candidate from another user 
function onCandidate(candidate) { 
   myConnection.addIceCandidate(new RTCIceCandidate(candidate)); 
}


您可以看到,我们建立了一个与我们的信令服务器的连接。当用户单击Login按钮时,应用程序将其用户名发送到服务器。如果登录成功,应用程序将创建RTCPeerConnection对象并设置onicecandidate处理程序,它将所有找到的icecandidates发送到另一个对等点。现在打开页面,尝试登录。您应该看到以下控制台输出:


establishing_connection.jpg


下一步我们要创建一个提议到远程节点,添加如下代码到client.js中:


//setup a peer connection with another user 

connectToOtherUsernameBtn.addEventListener("click", function () { 

 

   var otherUsername = otherUsernameInput.value; 

   connectedUser = otherUsername;

   if (otherUsername.length > 0) { 

      //make an offer 

      myConnection.createOffer(function (offer) { 

         console.log(); 

         send({ 

            type: "offer", 

            offer: offer 

         });

         myConnection.setLocalDescription(offer); 

      }, function (error) { 

         alert("An error has occurred."); 

      }); 

   } 

}); 

 

//when somebody wants to call us 

function onOffer(offer, name) { 

   connectedUser = name; 

   myConnection.setRemoteDescription(new RTCSessionDescription(offer)); 

   myConnection.createAnswer(function (answer) { 

      myConnection.setLocalDescription(answer); 

      send({ 

         type: "answer", 

         answer: answer 

      }); 

   }, function (error) { 

      alert("oops...error"); 

   }); 

}

  

//when another user answers to our offer 

function onAnswer(answer) { 

   myConnection.setRemoteDescription(new RTCSessionDescription(answer)); 

 

//when we got ice candidate from another user 

function onCandidate(candidate) { 

   myConnection.addIceCandidate(new RTCIceCandidate(candidate)); 

}



您可以看到,当用户单击Establish connection按钮时,应用程序会向其他节点提供SDP。我们还设置了onanswer和oncandidate处理程序。重新加载页面,在两个选项卡中打开它,使用两个用户登录,并尝试在它们之间建立连接。您应该看到以下控制台输出—


console_output.jpg


现在点对点链接已经建立成功. 下一章, 我们将添加视频和音频以及文本聊天支持。.