鸟语天空

WebRTC ICE 传输层

作者：追风剑情 发布于：2024-2-4 14:19 分类：Unity3d

  RTCIceTransport 接口定义了收发数据包的P2P传输通道，当需要获取 ICE 连接状态信息时，通过该接口进行访问。

  当调用 setLocalDescription() 或 setRemoteDescription()方法时，WebRTC自动创建 RTCIceTransport 对象，对象中的ICE 代理(ICE Agent)负责管理 ICE 的连接状态。

//RTCIceTransport的定义
interface RTCIceTransport : EventTarget {
	readonly attribute RTCIceRole role;
	readonly attribute RTCIceComponent component;
	readonly attribute RTCIceTransportState state;
	readonly attribute RrCIceGathererstate gatheringState;
	sequence<RTCIceCandidate> getLocalCandidates();
	sequence<RTCIceCandidate> getRemoteCandidates();
	RTCIceCandidatePair? getSelectedCandidatePair();
	RTCIceParameters? getLocalParameters();
	RTCIceParameters? getRemoteParameters();
	attribute EventHandler onstatechange;
	attribute EventHandler ongatheringstatechange;
	attribute EventHandler onselectedcandidatepairchange;
};  

RTCIceTransport 属性

1.role 只读

//RTCIceRole的定义
enum RTCIceRole {
	"unknown",
	"controlling",
	"controlled"
};  

RTCIceRole 枚举值说明
枚举值	说明
unknown	ICE代理的角色还没有确定
controlling	ICE 控制代理
controlled	ICE 受控代理

ICE 区分不同角色，帮助协商过程顺利完成。

2.component 只读

该属性返回当前对象使用的传输协议，类型为 RTCIceComponent。

//RTClceComponent的定义
enum RTCIceComponent {
	"rtp",
	"rtcp"
};  

RTCIceComponent 枚举值说明
枚举值	说明
rtp	当前对象使用的 RTP 协议
rtcp	当前对象使用的 RTCP 协议

3.state 只读

该属性表示ICE传输状态，类型为 RTCIceTransportState。

//RTCIceTransportState的定义
enum RTCIceTransportState {
	"new",
	"checking",
	"connected",
	"completed",
	"disconnected",
	"failed",
	"closed"
};  

RTCIceTransportState 枚举值说明
枚举值	枚举值说明
new	RTClceTransport正在收集候选地址，或者正在等待对等端返回ICE候选者地址
checking	RTCIceTransport 收到了对等端返回的ICE候选者地址，正在进行配对
connected	RTCIceTransport 找到了一条可用的网络连接。为了找到一个更优的网络路径RTCIceTransport仍然会继续进行ICE候选者地址收集和配对
completed	RTCIceTransport结束了ICE候选者地址的收集，并从对等端收到没有更多ICE 候选者地址的指令，最终执行配对过程，成功找到了可用的网络连接
disconnected	RTCIceTransport网络连接中断，这是一个可恢复的短暂状态，在弱网环境可能会频繁触发
failed	RTCIceTransport完成了ICE候选者收集，但是因为没有成功连通的候选者对导致配对失败。 除非ICE重启，否则该状态不会恢复，同时该状态不会导致DTLS传输层关闭。
closed	RTCIceTransport 对象已关闭，不再响应 STUN 请求。

4.gatheringState 只读

该属性表示ICE候选者的收集状态，类型为 RTCIceGathererState。

//RTCIceGathererState 的定义
enum RTCIceGathererState {
	"new",
	"gathering",
	"complete"
};  

RTCIceGathererState 属性说明
枚举值	枚举值说明
new	刚刚创建 RTCIceTransport，还没有开始收集ICE候选者信息
gathering	RTCIceTransport 正在收集ICE候选者信息
complete	RTCIceTranspont 完成了ICE候选者信息的收集，已经向对等端发送了ICE候选者结束标识

RTCIceTransport 方法

1.getLocalCandidates() 方法

该方法返回本地ICE候选组。ICE代理将收集到的新的ICE候选项放入候选组，同时触发事件 RTCPeerConnection:icecandidate。

localCandidates = RTCIceTransport.getLocalcandidates();

参数：无。
返回值：包含 RTCIceCandidate 对象的数组。每个 RTCIceCandidate 对象代表一个本地 ICE 候选项。

//getLocalCandidates()方法示例
const localCandidates = pc.getSenders()[0].transport.iceTransport.getLocalCandidates();
localCandidates.forEach((candidate, index) => {
	console.log("Candidate " + index + ":" + candidate.candidate);
});

2.getRemoteCandidates()方法

该方法返回对等端ICE候选组。

当本地应用程序调用 RTCPeerConnection.addIceCandidate()方法将对等端候选项加入ICE 会话时，调用该方法可获得包含此候选项的数组。

remoteCandidates = RTCIceTransport.getRemoteCandidates();

参数：无。
返回值：包含RTCIceCandidate对象的数组。每个RTCIceCandidate对象代表一个从对等端收到的 ICE 候选项。

//getRemoteCandidates() 方法示例
const remoteCandidates = pc.getSenders()[0].transport.iceTransport.getRemoteCandidates();
remoteCandidates.forEach((candidate, index) => {
	console.log("Candidate " + index + ":" + candidate.candidate);
});

3.getSelectedCandidatePair()方法

该方法返回ICE代理当前选择的候选对。

candidatePair = RTCIceTransport.getSelectedCandidatePair();

输入：无。
返回值：RTCIceCandidatePair 对象，描述了当前选择的 ICE 候选对。

//RTCIceCandidatePair的定义
dictionary RTCIceCandidatePair {
	RTCIceCandidate local;
	RTCIceCandidate remote;
};

其中，local 表示候选对中的本地候选项，remote 表示候选对中的对等端候选项。下面的代码清单 演示了获取并显示当前ICE候选对使用的网络协议。

//getSelectedCandidatePair()方法示例
const iceTransport = pc.getSenders()[0].transport.iceTransport;
const localProto = document.getElementById("local-protocol");
const remoteProto = document.getElementById("remote-protocol");

iceTransport.onselectedcandidatepairchange = (event) => {
	const pair = iceTransport.getSelectedCandidatePair();
	localProto.innerText = pair.local.protocol.toUpperCase();
	remoteProto.innerText = pair.remote.protocol.toUpperCase();
}

4.getLocalParameters()方法

该方法返回本地ICE参数。

当调用方法 RTCPeerConnection.setLocalDescription() 时，相应地设置了本地 ICE 参数。

parameters = RTCIceTransport.getLocalParameters();

参数：无。
返回值：RTCIceParameters 对象，如果未被设置，则返回 nul1。

//RTClceParameters的定义
dictionary RTCIceParameters {
	DOMString usernameFragment;
	DOMString password;
};

其中，usernameFragment 和 password 分别表示用户名和密码。

5.getRemoteParameters()方法

该方法返回对等端ICE的参数，返回值类型为RTCIceParameters，其用法基本与getLocalParameters()方法一致，不再赘述。

RTCIceTransport 事件

1.statechange 事件

当 RTClceTransport 状态发生改变时触发该事件，通过属性 RTCIceTransport.state 获取当前状态值，对应事件句柄 onstatechange。

//statechange事件句柄示例
let iceTransport = pc.getSenders()[0].transport.iceTransport;
iceTransport.onstatechange = ev => {
	if (iceTransport.state === "failed") {
		handleFailure(pc);
	}
}

也可以使用 addEventListener 监听 statechange 事件。

2.gatheringstatechange 事件

当ICE候选者的收集状态值发生改变时触发该事件，通过属性 gatheringState 获取当前状态值，对应事件句柄 ongatheringstatechange。

该事件与 icegatheringstatechange 相似，但 icegatheringstatechange 代表整个连接的候选收集状态，包括所有 RTCIceTransport，而 gatheringstatechange 只代表单个 RTCIceTranspor 的收集状态。

//gatheringstatechange事件句柄示例
pc.getSenders().forEach(sender => {
	sender.transport.iceTransport.ongatheringstatechange = ev => {
		let transport = ev.target;
		if (transport.gatheringState === "complete") {
			/* 这个传输通道已经完成了ICE候选者收集，但是其他通道可能仍在进行中 */
		}
	};
});

也可以使用 addEventListener 监听 gatheringstatechange 事件。

3.selectedcandidatepairchange 事件

当ICE代理选择了新的候选对时触发该事件，对应事件柄 onselectedcandidatepairchange。

在ICE协商过程中，从本地和对等端收集ICE候选者信息，当找到了一个有望成功建立网络连接的候选对，即触发事件selectedcandidatepairchange 时，使用 getSelectedCandidatePair() 方法可以获取此候选对。

ICE继续配对，如果找到了更优的候选对，则替换掉当前的，并再次触发 selectedcandidatepairchange 事件。

标签: Unity3d