2019-04-19 09:21:09 +00:00
<?xml version="1.0" encoding="UTF-8" ?>
2021-06-04 16:03:15 +00:00
<class name= "WebRTCPeerConnection" inherits= "RefCounted" version= "4.0" >
2019-04-19 09:21:09 +00:00
<brief_description >
2019-06-03 13:20:15 +00:00
Interface to a WebRTC peer connection.
2019-04-19 09:21:09 +00:00
</brief_description>
<description >
2019-06-03 13:20:15 +00:00
A WebRTC connection between the local computer and a remote peer. Provides an interface to connect, maintain and monitor the connection.
2019-06-14 22:04:55 +00:00
Setting up a WebRTC connection between two peers from now on) may not seem a trivial task, but it can be broken down into 3 main steps:
2019-06-03 13:20:15 +00:00
- The peer that wants to initiate the connection ([code]A[/code] from now on) creates an offer and send it to the other peer ([code]B[/code] from now on).
2019-06-27 10:34:26 +00:00
- [code]B[/code] receives the offer, generate and answer, and sends it to [code]A[/code]).
2019-06-14 22:04:55 +00:00
- [code]A[/code] and [code]B[/code] then generates and exchange ICE candidates with each other.
2019-06-03 13:20:15 +00:00
After these steps, the connection should become connected. Keep on reading or look into the tutorial for more information.
2019-04-19 09:21:09 +00:00
</description>
<tutorials >
</tutorials>
<methods >
<method name= "add_ice_candidate" >
2021-07-30 13:28:05 +00:00
<return type= "int" enum= "Error" />
<argument index= "0" name= "media" type= "String" />
<argument index= "1" name= "index" type= "int" />
<argument index= "2" name= "name" type= "String" />
2019-04-19 09:21:09 +00:00
<description >
2019-06-03 13:20:15 +00:00
Add an ice candidate generated by a remote peer (and received over the signaling server). See [signal ice_candidate_created].
2019-04-19 09:21:09 +00:00
</description>
</method>
2019-05-10 23:46:27 +00:00
<method name= "close" >
2021-07-30 13:28:05 +00:00
<return type= "void" />
2019-05-10 23:46:27 +00:00
<description >
2021-10-05 12:24:34 +00:00
Close the peer connection and all data channels associated with it.
[b]Note:[/b] You cannot reuse this object for a new connection unless you call [method initialize].
2019-05-10 23:46:27 +00:00
</description>
</method>
<method name= "create_data_channel" >
2021-07-30 13:28:05 +00:00
<return type= "WebRTCDataChannel" />
<argument index= "0" name= "label" type= "String" />
2022-01-18 10:31:15 +00:00
<argument index= "1" name= "options" type= "Dictionary" default= "{}" />
2019-05-10 23:46:27 +00:00
<description >
2019-06-03 13:20:15 +00:00
Returns a new [WebRTCDataChannel] (or [code]null[/code] on failure) with given [code]label[/code] and optionally configured via the [code]options[/code] dictionary. This method can only be called when the connection is in state [constant STATE_NEW].
There are two ways to create a working data channel: either call [method create_data_channel] on only one of the peer and listen to [signal data_channel_received] on the other, or call [method create_data_channel] on both peers, with the same values, and the [code]negotiated[/code] option set to [code]true[/code].
Valid [code]options[/code] are:
2019-06-14 22:04:55 +00:00
[codeblock]
2019-06-03 13:20:15 +00:00
{
2021-05-20 10:07:26 +00:00
"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.
2019-06-03 13:20:15 +00:00
"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.
}
2019-06-14 22:04:55 +00:00
[/codeblock]
2019-06-21 23:04:47 +00:00
[b]Note:[/b] You must keep a reference to channels created this way, or it will be closed.
2019-05-10 23:46:27 +00:00
</description>
</method>
2019-04-19 09:21:09 +00:00
<method name= "create_offer" >
2021-07-30 13:28:05 +00:00
<return type= "int" enum= "Error" />
2019-04-19 09:21:09 +00:00
<description >
2019-06-03 13:20:15 +00:00
Creates a new SDP offer to start a WebRTC connection with a remote peer. At least one [WebRTCDataChannel] must have been created before calling this method.
2019-06-27 10:34:26 +00:00
If this functions returns [constant OK], [signal session_description_created] will be called when the session is ready to be sent.
2019-04-19 09:21:09 +00:00
</description>
</method>
<method name= "get_connection_state" qualifiers= "const" >
2021-07-30 13:28:05 +00:00
<return type= "int" enum= "WebRTCPeerConnection.ConnectionState" />
2019-05-10 23:46:27 +00:00
<description >
2019-06-03 13:20:15 +00:00
Returns the connection state. See [enum ConnectionState].
2019-05-10 23:46:27 +00:00
</description>
</method>
<method name= "initialize" >
2021-07-30 13:28:05 +00:00
<return type= "int" enum= "Error" />
2022-01-18 10:31:15 +00:00
<argument index= "0" name= "configuration" type= "Dictionary" default= "{}" />
2019-04-19 09:21:09 +00:00
<description >
2019-06-03 13:20:15 +00:00
Re-initialize this peer connection, closing any previously active connection, and going back to state [constant STATE_NEW]. A dictionary of [code]options[/code] can be passed to configure the peer connection.
Valid [code]options[/code] are:
2019-06-14 22:04:55 +00:00
[codeblock]
2019-06-03 13:20:15 +00:00
{
"iceServers": [
{
"urls": [ "stun:stun.example.com:3478" ], # One or more STUN servers.
},
{
"urls": [ "turn:turn.example.com:3478" ], # One or more TURN servers.
"username": "a_username", # Optional username for the TURN server.
2020-09-08 09:10:57 +00:00
"credential": "a_password", # Optional password for the TURN server.
2019-06-03 13:20:15 +00:00
}
]
}
2019-06-14 22:04:55 +00:00
[/codeblock]
2019-04-19 09:21:09 +00:00
</description>
</method>
<method name= "poll" >
2021-07-30 13:28:05 +00:00
<return type= "int" enum= "Error" />
2019-04-19 09:21:09 +00:00
<description >
2019-06-14 22:04:55 +00:00
Call this method frequently (e.g. in [method Node._process] or [method Node._physics_process]) to properly receive signals.
2019-04-19 09:21:09 +00:00
</description>
</method>
<method name= "set_local_description" >
2021-07-30 13:28:05 +00:00
<return type= "int" enum= "Error" />
<argument index= "0" name= "type" type= "String" />
<argument index= "1" name= "sdp" type= "String" />
2019-04-19 09:21:09 +00:00
<description >
2019-06-03 13:20:15 +00:00
Sets the SDP description of the local peer. This should be called in response to [signal session_description_created].
2020-06-04 19:10:34 +00:00
After calling this function the peer will start emitting [signal ice_candidate_created] (unless an [enum Error] different from [constant OK] is returned).
2019-04-19 09:21:09 +00:00
</description>
</method>
<method name= "set_remote_description" >
2021-07-30 13:28:05 +00:00
<return type= "int" enum= "Error" />
<argument index= "0" name= "type" type= "String" />
<argument index= "1" name= "sdp" type= "String" />
2019-04-19 09:21:09 +00:00
<description >
2019-06-03 13:20:15 +00:00
Sets the SDP description of the remote peer. This should be called with the values generated by a remote peer and received over the signaling server.
If [code]type[/code] is [code]offer[/code] the peer will emit [signal session_description_created] with the appropriate answer.
If [code]type[/code] is [code]answer[/code] the peer will start emitting [signal ice_candidate_created].
2019-04-19 09:21:09 +00:00
</description>
</method>
</methods>
<signals >
2019-05-10 23:46:27 +00:00
<signal name= "data_channel_received" >
2022-01-28 14:35:25 +00:00
<argument index= "0" name= "channel" type= "WebRTCDataChannel" />
2019-05-10 23:46:27 +00:00
<description >
2019-06-03 13:20:15 +00:00
Emitted when a new in-band channel is received, i.e. when the channel was created with [code]negotiated: false[/code] (default).
2020-01-23 10:14:14 +00:00
The object will be an instance of [WebRTCDataChannel]. You must keep a reference of it or it will be closed automatically. See [method create_data_channel].
2019-05-10 23:46:27 +00:00
</description>
</signal>
<signal name= "ice_candidate_created" >
2021-07-30 13:28:05 +00:00
<argument index= "0" name= "media" type= "String" />
<argument index= "1" name= "index" type= "int" />
<argument index= "2" name= "name" type= "String" />
2019-04-19 09:21:09 +00:00
<description >
2019-06-03 13:20:15 +00:00
Emitted when a new ICE candidate has been created. The three parameters are meant to be passed to the remote peer over the signaling server.
2019-04-19 09:21:09 +00:00
</description>
</signal>
2019-05-10 23:46:27 +00:00
<signal name= "session_description_created" >
2021-07-30 13:28:05 +00:00
<argument index= "0" name= "type" type= "String" />
<argument index= "1" name= "sdp" type= "String" />
2019-04-19 09:21:09 +00:00
<description >
2019-06-03 13:20:15 +00:00
Emitted after a successful call to [method create_offer] or [method set_remote_description] (when it generates an answer). The parameters are meant to be passed to [method set_local_description] on this object, and sent to the remote peer over the signaling server.
2019-04-19 09:21:09 +00:00
</description>
</signal>
</signals>
<constants >
<constant name= "STATE_NEW" value= "0" enum= "ConnectionState" >
2019-06-03 13:20:15 +00:00
The connection is new, data channels and an offer can be created in this state.
2019-04-19 09:21:09 +00:00
</constant>
<constant name= "STATE_CONNECTING" value= "1" enum= "ConnectionState" >
2019-06-21 23:04:47 +00:00
The peer is connecting, ICE is in progress, none of the transports has failed.
2019-04-19 09:21:09 +00:00
</constant>
<constant name= "STATE_CONNECTED" value= "2" enum= "ConnectionState" >
2019-06-03 13:20:15 +00:00
The peer is connected, all ICE transports are connected.
2019-04-19 09:21:09 +00:00
</constant>
<constant name= "STATE_DISCONNECTED" value= "3" enum= "ConnectionState" >
2019-06-03 13:20:15 +00:00
At least one ICE transport is disconnected.
2019-04-19 09:21:09 +00:00
</constant>
<constant name= "STATE_FAILED" value= "4" enum= "ConnectionState" >
2019-06-03 13:20:15 +00:00
One or more of the ICE transports failed.
2019-04-19 09:21:09 +00:00
</constant>
<constant name= "STATE_CLOSED" value= "5" enum= "ConnectionState" >
2019-06-03 13:20:15 +00:00
The peer connection is closed (after calling [method close] for example).
2019-04-19 09:21:09 +00:00
</constant>
</constants>
</class>