WebRTCPeerConnection

继承： RefCounted < Object

派生： WebRTCPeerConnectionExtension

与 WebRTC 对等体连接的接口。

描述

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

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

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

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

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

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

方法

信号

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。