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 候選。
在這些步驟之後,連接應該就建立起來了。有關詳細資訊,請參閱連結的教學。
教學
方法
add_ice_candidate(media: String, index: int, name: String) |
|
void |
close() |
create_data_channel(label: String, options: Dictionary = {}) |
|
get_connection_state() const |
|
get_gathering_state() const |
|
get_signaling_state() const |
|
initialize(configuration: Dictionary = {}) |
|
poll() |
|
void |
set_default_extension(extension_class: StringName) static |
set_local_description(type: String, sdp: String) |
|
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.
建立一個新的 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 伺服器的密碼,選填。
}
]
}
經常呼叫這個方法以正確接收訊號,例如在 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。