Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

WebRTCPeerConnection

继承： RefCounted < Object

派生： WebRTCPeerConnectionExtension

与 WebRTC 对等体连接的接口。

描述

本地计算机和远程对等体之间的 WebRTC 连接。提供一个接口来连接、维护和监控连接。

在两个对等体之间建立 WebRTC 连接看上去可能不是一项简单的任务，但它可以分解为 3 个主要步骤。

• 想要启动连接的对等体（A从现在开始）创建一个提交，并将其发送给另一个对等体（B从现在开始）。

• B 收到要约，生成和回答，并将其发送给 A）。

• A 和 B 然后生成并相互交换 ICE 候选。

在这些步骤之后，连接应该成功建立。继续阅读或查看教程以了解更多信息。

方法

Error	add_ice_candidate(media: String, index: int, name: String)
void	close()
WebRTCDataChannel	create_data_channel(label: String, options: Dictionary = {})
Error	create_offer()
ConnectionState	get_connection_state() const
GatheringState	get_gathering_state() const
SignalingState	get_signaling_state() const
Error	initialize(configuration: Dictionary = {})
Error	poll()
void	set_default_extension(extension_class: StringName) static
Error	set_local_description(type: String, sdp: String)
Error	set_remote_description(type: String, sdp: String)

---

信号

data_channel_received(channel: WebRTCDataChannel) 🔗

当收到一个新的带内通道时发出，即在通道是用negotiated: false（默认）。

该对象将是WebRTCDataChannel的一个实例。你必须保持它的引用，否则它将被自动关闭。参阅create_data_channel。

---

ice_candidate_created(media: String, index: int, name: String) 🔗

当新的 ICE 候选者被创建时触发。这三个参数是为了通过信号服务器传递给远程对等体。

---

session_description_created(type: String, sdp: String) 🔗

在成功调用 create_offer 或 set_remote_description 后触发，当它产生一个应答时。这些参数是为了传递给这个对象上的 set_local_description，并通过信号服务器发送给远程对等体。

---

枚举

enum ConnectionState: 🔗

ConnectionState STATE_NEW = 0

连接是新的，数据通道和提交可以在这种状态下创建。

ConnectionState STATE_CONNECTING = 1

对等体正在连接，ICE 正在进行中，没有任何传输失败。

ConnectionState STATE_CONNECTED = 2

对等体已连接，所有的 ICE 传输都已连接。

ConnectionState STATE_DISCONNECTED = 3

至少有一个 ICE 传输被断开连接。

ConnectionState STATE_FAILED = 4

一个或更多的 ICE 传输失败。

ConnectionState STATE_CLOSED = 5

对等连接已关闭，例如在调用 close 后。

---

enum GatheringState: 🔗

GatheringState GATHERING_STATE_NEW = 0

对等体连接刚刚建立，还没有做任何联网工作。

GatheringState GATHERING_STATE_GATHERING = 1

ICE 代理正在收集候选连接。

GatheringState GATHERING_STATE_COMPLETE = 2

ICE 代理已完成候选连接的收集。如果发生了需要收集新候选的情况，例如新添加了接口、新添加了 ICE 服务器，则会返回收集状态，进行候选项的收集。

---

enum SignalingState: 🔗

SignalingState SIGNALING_STATE_STABLE = 0

没有正在进行的要约和答复的交换。这可能意味着 WebRTCPeerConnection 是新的（STATE_NEW），或者协商已完成并且连接已经建立（STATE_CONNECTED）。

SignalingState SIGNALING_STATE_HAVE_LOCAL_OFFER = 1

本地对等体已调用 set_local_description，正在传入代表邀约的 SDP（通常由调用 create_offer 创建），邀约已成功应用。

SignalingState SIGNALING_STATE_HAVE_REMOTE_OFFER = 2

远程对等体已创建邀约，并将其使用信号服务器传递给了本地对等体，本地对等体已调用 set_remote_description 将邀约设置为远程描述。

SignalingState SIGNALING_STATE_HAVE_LOCAL_PRANSWER = 3

已应用远程对等体发送的邀约，已创建恢复并调用了 set_local_description 进行应用。这个临时应答描述了支持的媒体格式等信息，但可能不包含完整的 ICE 候选项。后续会单独发送更多候选项。

SignalingState SIGNALING_STATE_HAVE_REMOTE_PRANSWER = 4

已经接收到初步回应，并已成功地应用到之前通过调用 set_local_description 发送并建立的邀请中。

SignalingState SIGNALING_STATE_CLOSED = 5

该 WebRTCPeerConnection 已关闭连接。

---

方法说明

Error add_ice_candidate(media: String, index: int, name: String) 🔗

添加一个由远程对等体产生的冻结候选，并通过信令服务器接收。请参阅ice_candidate_created。

---

void close() 🔗

关闭对等体连接和与之相关的所有数据通道。

注意：你不能为一个新的连接重复使用这个对象，除非你调用 initialize。

---

WebRTCDataChannel create_data_channel(label: String, options: Dictionary = {}) 🔗

返回新的 WebRTCDataChannel，或在失败时返回 null，具有给定的 label，并通过 options 字典进行配置。这个方法只有在连接处于 STATE_NEW 状态时才能被调用。

有两种方法来创建工作数据通道：要么只在其中一个对等体上调用 create_data_channel，并在另一个对等体上监听data_channel_received，要么在两个对等体上调用 create_data_channel，数值相同，并将 "negotiated" 选项设置为 true。

有效的 options 是：

{
    "negotiated": true, # 当设置为 "true"时，默认关闭，意味着该通道是在频带外协商的。"id"也必须被设置。"data_channel_received" 将不会被调用。
    "id":1, # 当 "negotiated"为真时，这个值也必须被设置为两个对等体的相同值。

    # 只能指定maxRetransmits和maxPacketLifeTime中的一个，不能同时指定。它们会使信道变得不可靠，但在实时性方面会更好。
    "maxRetransmits":1, # 指定对等体在数据包未被确认时尝试重传的最大次数。
    "maxPacketLifeTime":100, # 指定放弃重传未被确认的数据包之前的最大时间，以毫秒为单位。
    "ordered": true, # 当处于不可靠模式时，即 "maxRetransmits "或 "maxPacketLifetime "被设置，"ordered"指定是否要强制执行数据包排序，默认为true。

    "protocol":"my-custom-protocol", # 这个通道的自定义子协议字符串。
}

注意：你必须保持对以这种方式创建的通道的引用，否则它将被关闭。

---

Error create_offer() 🔗

创建一个新的 SDP 提交，以开始与远程对等体的 WebRTC 连接。在调用此方法之前，至少要创建一个 WebRTCDataChannel。

如果这个函数返回 @GlobalScope.OK，当会话准备好被发送时，session_description_created 将被调用。

---

ConnectionState get_connection_state() const 🔗

返回连接状态。见 ConnectionState。

---

GatheringState get_gathering_state() const 🔗

返回连接的 ICE GatheringState。你可以据此来检测，例如，ICE 候选项的收集是否完成。

---

SignalingState get_signaling_state() const 🔗

连接或重新连接到另一个对等体时，返回连接本地端的信令状态。

---

Error initialize(configuration: Dictionary = {}) 🔗

重新初始化这个对等体连接，关闭任何先前活动的连接，并回到 STATE_NEW 状态。传入配置选项字典 configuration 能够对该对等体连接进行配置。

有效的 configuration 选项有：

{
    "iceServers": [
        {
            "urls": [ "stun:stun.example.com:3478" ], # 若干 STUN 服务器。
        },
        {
            "urls": [ "turn:turn.example.com:3478" ], # 若干 TURN 服务器。
            "username": "a_username", # TURN 服务器的用户名，选填。
            "credential": "a_password", # TURN 服务器的密码，选填。
        }
    ]
}

---

Error poll() 🔗

经常调用这个方法以正确接收信号，例如在 Node._process 或 Node._physics_process 中。

---

void set_default_extension(extension_class: StringName) static 🔗

将 extension_class 设置为创建新 WebRTCPeerConnection 时返回的默认 WebRTCPeerConnectionExtension。

---

Error set_local_description(type: String, sdp: String) 🔗

设置本地对等体的 SDP 描述。这应是在响应 session_description_created 时调用的。

调用此函数后，对等体将开始发出 ice_candidate_created，除非返回与 @GlobalScope.OK 不同的 Error。

---

Error set_remote_description(type: String, sdp: String) 🔗

设置远程对等体的 SDP 描述。应用远程对等体产生的值来调用，并通过信号服务器接收。

如果 type 为 "offer"，对等体将发出 session_description_created 并给出适当的应答。

如果 type 为 "answer"，对等体将开始发出 ice_candidate_created。