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.

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 = {}) 🔗

Returns a new WebRTCDataChannel (or null on failure) with given label and optionally configured via the options dictionary. This method can only be called when the connection is in state STATE_NEW.

There are two ways to create a working data channel: either call create_data_channel() on only one of the peer and listen to data_channel_received on the other, or call create_data_channel() on both peers, with the same values, and the "negotiated" option set to true.

Valid options are:

{
    "negotiated": true, # When set to true (default off), means the channel is negotiated out of band. "id" must be set too. "data_channel_received" will not be called.
    "id": 1, # When "negotiated" is true this value must also be set to the same value on both peer.

    # Only one of maxRetransmits and maxPacketLifeTime can be specified, not both. They make the channel unreliable (but also better at real time).
    "maxRetransmits": 1, # Specify the maximum number of attempt the peer will make to retransmits packets if they are not acknowledged.
    "maxPacketLifeTime": 100, # Specify the maximum amount of time before giving up retransmitions of unacknowledged packets (in milliseconds).
    "ordered": true, # When in unreliable mode (i.e. either "maxRetransmits" or "maxPacketLifeTime" is set), "ordered" (true by default) specify if packet ordering is to be enforced.

    "protocol": "my-custom-protocol", # A custom sub-protocol string for this channel.
}

Note: You must keep a reference to channels created this way, or it will be closed.


Error create_offer() 🔗

建立一個新的 SDP 提交,以開始與遠端對等體的 WebRTC 連接。在呼叫此方法之前,至少要建立一個 WebRTCDataChannel。

如果這個函式返回 @GlobalScope.OK,當會話準備好被發送時,session_description_created 將被呼叫。


ConnectionState get_connection_state() const 🔗

回傳連接狀態。


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。