Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

WebRTCPeerConnection

继承: RefCounted < Object

派生: WebRTCPeerConnectionExtension

与 WebRTC 对等体连接的接口。

描述

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

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

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

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

  • AB 然后生成并相互交换 ICE 候选。

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

方法

Error

add_ice_candidate ( String media, int index, String name )

void

close ( )

WebRTCDataChannel

create_data_channel ( String label, Dictionary options={} )

Error

create_offer ( )

ConnectionState

get_connection_state ( ) const

GatheringState

get_gathering_state ( ) const

SignalingState

get_signaling_state ( ) const

Error

initialize ( Dictionary configuration={} )

Error

poll ( )

void

set_default_extension ( StringName extension_class ) static

Error

set_local_description ( String type, String sdp )

Error

set_remote_description ( String type, String sdp )


信号

data_channel_received ( WebRTCDataChannel channel )

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

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


ice_candidate_created ( String media, int index, String name )

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


session_description_created ( String type, String sdp )

在成功调用 create_offerset_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 ( String media, int index, String name )

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


void close ( )

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

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


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

返回新的 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

返回在连接或重新连接至其他对等体时,连接本地端的 SignalingState


Error initialize ( Dictionary configuration={} )

重新初始化这个对等体连接,关闭任何先前活动的连接,并回到 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._processNode._physics_process 中。


void set_default_extension ( StringName extension_class ) static

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


Error set_local_description ( String type, String sdp )

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

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


Error set_remote_description ( String type, String sdp )

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

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

如果 type"answer",对等体将开始发出 ice_candidate_created