[TOC] ## RTCPeerConnection RTCPeerConnection 接口代表一個由本地計算機到遠端的WebRTC連接。該接口提供了創建，保持，監控，關閉連接的方法的實現。 ### sample 1. 添加流 ``` var pc = new RTCPeerConnection(); // 設置添加流事件 pc.onaddstream = function(obj) { var vid = document.createElement("video"); document.appendChild(vid); vid.srcObject = obj.stream; } // 幫助函數 function endCall() { var videos = document.getElementsByTagName("video"); for (var i = 0; i < videos.length; i++) { videos[i].pause(); } pc.close(); } function error(err) { endCall(); } ``` 2. 呼叫初始化 ``` 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); }) ``` 3. 呼叫回答 ``` 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); }) ``` 4. 處理應答 ``` // pc was set up earlier when we made the original offer var offer = getResponseFromFriend(); pc.setRemoteDescription(new RTCSessionDescription(offer), function() { }, error); ``` ## 事件 ### onaddstream 是收到`[addstream](https://developer.mozilla.org/zh-CN/docs/Web/Reference/Events/addstream "/zh-CN/docs/Web/Reference/Events/addstream")`事件時調用的事件處理器。?Such an event is 當[`MediaStream`](https://developer.mozilla.org/zh-CN/docs/Web/API/MediaStream)被遠端機器添加到這條連接時，該事件會被觸發。?當調用[`RTCPeerConnection.setRemoteDescription()`](https://developer.mozilla.org/zh-CN/docs/Web/API/RTCPeerConnection/setRemoteDescription)方法時，這個事件就會被立即觸發，它不會等待SDP協商的結果 ### ondatachannel 是收到datachannel 事件時調用的事件處理器。 當一個 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.'); }; }; ``` ### onicecandidate 只要本地代理ICE 需要通過信令服務器傳遞信息給其他對等端時就會觸發。 ``` pc.onicecandidate = function(event) { if (event.candidate) { // Send the candidate to the remote peer } else { // All ICE candidates have been sent } } ``` ### oniceconnectionstatechange 是收到iceconnectionstatechange事件時調用的事件處理器 。 當iceConnectionState 改變時，這個事件被觸發。 ``` pc.oniceconnectionstatechange = function(event) { if (pc.iceConnectionState === "failed" || pc.iceConnectionState === "disconnected" || pc.iceConnectionState === "closed") { // Handle the failure } }; ``` ### onnegotiationneeded 發生需要會話協商的更改時，將觸發此事件 ## 方法 ### createOffer() 生成一個offer，它是一個帶有特定的配置信息尋找遠端匹配機器（peer）的請求。 ``` 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 }); ``` ### createAnswer() 在協調一條連接中的兩端offer/answers時，根據從遠端發來的offer生成一個answer ``` pc.createAnswer().then(function(answer) { return pc.setLocalDescription(answer); }) .then(function() { // Send the answer to the remote peer through the signaling server. }) .catch(handleGetUserMediaError); ``` ### setLocalDescription() 改變與連接相關的本地描述。這個描述定義了連接的屬性，例如：連接的編碼方式。連接會受到它的改變的影響 實例1: ``` myPeerConnection.createOffer().then(function(offer) { return myPeerConnection.setLocalDescription(offer); }); // 等價于 myPeerConnection.createOffer().then(function(offer) { return myPeerConnection.setLocalDescription(new RTCSessionDescription(offer)); }); ``` 實例2: **隱式描述** 無參數形式的優點之一 setLocalDescription() 是，它使您可以大大簡化協商代碼 ``` pc.addEventListener("negotiationneeded", async (event) => { await pc.setLocalDescription(); signalRemotePeer({ description: pc.localDescription }); }); ``` **顯示** ``` async function handleNegotiationNeededEvent() { try { const offer = await pc.createOffer(); pc.setLocalDescription(offer); signalRemotePeer({ description: pc.localDescription }); } catch(err) { reportError(err); } } ``` ### setRemoteDescription() - 改變與連接相關的遠端描述。這個描述定義了連接的屬性，例如：連接的編碼方式。連接會受到它的改變的影響 - 連接的offer通常來自于負責匹配的服務器所發送的數據。執行者應調用此方法設置遠程描述，然后生成發送到對端計算機的answer ``` 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 }) }) }); ``` ### addIceCandidate() - 這是一個實驗中的功能 - 當本機當前頁面的 RTCPeerConnection 接收到一個從遠端頁面通過信號通道發來的新的 ICE 候選地址信息，本機可以通過調用RTCPeerConnection.addIceCandidate() 來添加一個 ICE 代理 ``` 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()"); }); ``` ### getConfiguration() RTCPeerConnection上調用該方法的當前配置 ``` let configuration = myPeerConnection.getConfiguration(); if ((configuration.certificates != undefined) && (!configuration.certificates.length)) { RTCPeerConnection.generateCertificate({ name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256', modulusLength: 2048, publicExponent: new Uint8Array([1, 0, 1]) }).then(function(cert) { configuration.certificates = [cert]; myPeerConnection.setConfiguration(configuration); }); } ``` ### getSenders (原 getLocalStreams ) - 返回一個RTCRtpSender對象數組 ，每個對象代表負責傳輸一個軌道的數據的RTP發送方 實例:靜音 ``` function setMuting(pc, muting) { let senderList = pc.getSenders(); senderList.forEach(sender) { sender.track.enabled = !muting; } } ``` ### getReceivers (原 getReceivers) 返回一個RTCRtpReceiver對象數組，每個對象代表一個RTP接收器 ### removeStream 移除媒體流 ``` 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); ``` ### close 關閉當前對等連接 ``` var pc = new RTCPeerConnection(); var dc = pc.createDataChannel("my channel"); dc.onmessage = function (event) { console.log("received: " + event.data); pc.close(); // We decided to close after the first received message }; dc.onopen = function () { console.log("datachannel open"); }; dc.onclose = function () { console.log("datachannel close"); }; ``` ### createDataChannel 創建一個可以發送任意數據的數據通道(data channel)。常用于后臺傳輸內容, 例如: 圖像, 文件傳輸, 聊天文字, 游戲數據更新包, 等等 實例1: ``` // 邀約方 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); } // 應答方 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); } } ``` 實例2:使用約定的id ``` 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); } ``` ### getStats 關整體連接或指定的統計信息的數據進行解析 ``` window.setInterval(function() { myPeerConnection.getStats(null).then(stats => { let statsOutput = ""; stats.forEach(report => { statsOutput += `<h2>Report: ${report.type}</h2>\n<strong>ID:</strong> ${report.id}<br>\n` + `<strong>Timestamp:</strong> ${report.timestamp}<br>\n`; // Now the statistics for this report; we intentially drop the ones we // sorted to the top above Object.keys(report).forEach(statName => { if (statName !== "id" && statName !== "timestamp" && statName !== "type") { statsOutput += `<strong>${statName}:</strong> ${report[statName]}<br>\n`; } }); }); document.querySelector(".stats-box").innerHTML = statsOutput; }); }, 1000); ``` ### getStreamById (棄用) ``` var stream = pc.getStreamById(myTrackId); if (stream) { console.log("Found stream: " + stream.id); } ``` ### addStream (棄用,推薦用 addTrack) ``` navigator.mediaDevices.getUserMedia({video:true, audio:true}, function(stream) { var pc = new RTCPeerConnection(); pc.addStream(stream); }); ```