WebRTCPeerConnection
Inherited By: WebRTCPeerConnectionGDNative
Interface to a WebRTC peer connection.
Description
A WebRTC connection between the local computer and a remote peer. Provides an interface to connect, maintain and monitor the connection.
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:
- The peer that wants to initiate the connection (
A
from now on) creates an offer and send it to the other peer (B
from now on). B
receives the offer, generate and answer, and sends it toA
).A
andB
then generates and exchange ICE candidates with each other.
After these steps, the connection should become connected. Keep on reading or look into the tutorial for more information.
Methods
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 |
Error | initialize ( Dictionary configuration={ } ) |
Error | poll ( ) |
Error | set_local_description ( String type, String sdp ) |
Error | set_remote_description ( String type, String sdp ) |
Signals
- data_channel_received ( Object channel )
Emitted when a new in-band channel is received, i.e. when the channel was created with negotiated: false
(default).
The object will be an instance of WebRTCDataChannel. You must keep a reference of it or it will be closed automatically. See create_data_channel.
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.
Emitted after a successful call to create_offer or set_remote_description (when it generates an answer). The parameters are meant to be passed to set_local_description on this object, and sent to the remote peer over the signaling server.
Enumerations
enum ConnectionState:
- STATE_NEW = 0 —- The connection is new, data channels and an offer can be created in this state.
- STATE_CONNECTING = 1 —- The peer is connecting, ICE is in progress, none of the transports has failed.
- STATE_CONNECTED = 2 —- The peer is connected, all ICE transports are connected.
- STATE_DISCONNECTED = 3 —- At least one ICE transport is disconnected.
- STATE_FAILED = 4 —- One or more of the ICE transports failed.
- STATE_CLOSED = 5 —- The peer connection is closed (after calling close for example).
Method Descriptions
Add an ice candidate generated by a remote peer (and received over the signaling server). See ice_candidate_created.
- void close ( )
Close the peer connection and all data channels associated with it. Note, you cannot reuse this object for a new connection unless you call initialize.
- WebRTCDataChannel create_data_channel ( String label, Dictionary options={ } )
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 ( )
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.
If this functions returns @GlobalScope.OK, session_description_created will be called when the session is ready to be sent.
- ConnectionState get_connection_state ( ) const
Returns the connection state. See ConnectionState.
- Error initialize ( Dictionary configuration={ } )
Re-initialize this peer connection, closing any previously active connection, and going back to state STATE_NEW. A dictionary of options
can be passed to configure the peer connection.
Valid options
are:
{
"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.
"credential": "a_password", # Optional password for the TURN server.
}
]
}
- Error poll ( )
Call this method frequently (e.g. in Node._process or Node._physics_process) to properly receive signals.
Sets the SDP description of the local peer. This should be called in response to session_description_created.
After calling this function the peer will start emitting ice_candidate_created (unless an Error different from @GlobalScope.OK is returned).
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 type
is offer
the peer will emit session_description_created with the appropriate answer.
If type
is answer
the peer will start emitting ice_candidate_created.