:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/3.6/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/3.6/modules/webrtc/doc_classes/WebRTCPeerConnection.xml. .. _class_WebRTCPeerConnection: WebRTCPeerConnection ==================== **Inherits:** :ref:`Reference` **<** :ref:`Object` **Inherited By:** :ref:`WebRTCPeerConnectionGDNative` Interface to a WebRTC peer connection. .. rst-class:: classref-introduction-group 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 to ``A``). - ``A`` and ``B`` 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. .. rst-class:: classref-reftable-group Methods ------- .. table:: :widths: auto +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`add_ice_candidate` **(** :ref:`String` media, :ref:`int` index, :ref:`String` name **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`close` **(** **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`WebRTCDataChannel` | :ref:`create_data_channel` **(** :ref:`String` label, :ref:`Dictionary` options={ } **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`create_offer` **(** **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`ConnectionState` | :ref:`get_connection_state` **(** **)** |const| | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`initialize` **(** :ref:`Dictionary` configuration={ } **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`poll` **(** **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`set_local_description` **(** :ref:`String` type, :ref:`String` sdp **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`set_remote_description` **(** :ref:`String` type, :ref:`String` sdp **)** | +-------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Signals ------- .. _class_WebRTCPeerConnection_signal_data_channel_received: .. rst-class:: classref-signal **data_channel_received** **(** :ref:`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 :ref:`WebRTCDataChannel`. You must keep a reference of it or it will be closed automatically. See :ref:`create_data_channel`. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_signal_ice_candidate_created: .. rst-class:: classref-signal **ice_candidate_created** **(** :ref:`String` media, :ref:`int` index, :ref:`String` name **)** 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. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_signal_session_description_created: .. rst-class:: classref-signal **session_description_created** **(** :ref:`String` type, :ref:`String` sdp **)** Emitted after a successful call to :ref:`create_offer` or :ref:`set_remote_description` (when it generates an answer). The parameters are meant to be passed to :ref:`set_local_description` on this object, and sent to the remote peer over the signaling server. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_WebRTCPeerConnection_ConnectionState: .. rst-class:: classref-enumeration enum **ConnectionState**: .. _class_WebRTCPeerConnection_constant_STATE_NEW: .. rst-class:: classref-enumeration-constant :ref:`ConnectionState` **STATE_NEW** = ``0`` The connection is new, data channels and an offer can be created in this state. .. _class_WebRTCPeerConnection_constant_STATE_CONNECTING: .. rst-class:: classref-enumeration-constant :ref:`ConnectionState` **STATE_CONNECTING** = ``1`` The peer is connecting, ICE is in progress, none of the transports has failed. .. _class_WebRTCPeerConnection_constant_STATE_CONNECTED: .. rst-class:: classref-enumeration-constant :ref:`ConnectionState` **STATE_CONNECTED** = ``2`` The peer is connected, all ICE transports are connected. .. _class_WebRTCPeerConnection_constant_STATE_DISCONNECTED: .. rst-class:: classref-enumeration-constant :ref:`ConnectionState` **STATE_DISCONNECTED** = ``3`` At least one ICE transport is disconnected. .. _class_WebRTCPeerConnection_constant_STATE_FAILED: .. rst-class:: classref-enumeration-constant :ref:`ConnectionState` **STATE_FAILED** = ``4`` One or more of the ICE transports failed. .. _class_WebRTCPeerConnection_constant_STATE_CLOSED: .. rst-class:: classref-enumeration-constant :ref:`ConnectionState` **STATE_CLOSED** = ``5`` The peer connection is closed (after calling :ref:`close` for example). .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_WebRTCPeerConnection_method_add_ice_candidate: .. rst-class:: classref-method :ref:`Error` **add_ice_candidate** **(** :ref:`String` media, :ref:`int` index, :ref:`String` name **)** Add an ice candidate generated by a remote peer (and received over the signaling server). See :ref:`ice_candidate_created`. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_close: .. rst-class:: classref-method 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 :ref:`initialize`. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_create_data_channel: .. rst-class:: classref-method :ref:`WebRTCDataChannel` **create_data_channel** **(** :ref:`String` label, :ref:`Dictionary` options={ } **)** Returns a new :ref:`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 :ref:`STATE_NEW`. There are two ways to create a working data channel: either call :ref:`create_data_channel` on only one of the peer and listen to :ref:`data_channel_received` on the other, or call :ref:`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. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_create_offer: .. rst-class:: classref-method :ref:`Error` **create_offer** **(** **)** Creates a new SDP offer to start a WebRTC connection with a remote peer. At least one :ref:`WebRTCDataChannel` must have been created before calling this method. If this functions returns :ref:`@GlobalScope.OK`, :ref:`session_description_created` will be called when the session is ready to be sent. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_get_connection_state: .. rst-class:: classref-method :ref:`ConnectionState` **get_connection_state** **(** **)** |const| Returns the connection state. See :ref:`ConnectionState`. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_initialize: .. rst-class:: classref-method :ref:`Error` **initialize** **(** :ref:`Dictionary` configuration={ } **)** Re-initialize this peer connection, closing any previously active connection, and going back to state :ref:`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. } ] } .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_poll: .. rst-class:: classref-method :ref:`Error` **poll** **(** **)** Call this method frequently (e.g. in :ref:`Node._process` or :ref:`Node._physics_process`) to properly receive signals. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_set_local_description: .. rst-class:: classref-method :ref:`Error` **set_local_description** **(** :ref:`String` type, :ref:`String` sdp **)** Sets the SDP description of the local peer. This should be called in response to :ref:`session_description_created`. After calling this function the peer will start emitting :ref:`ice_candidate_created` (unless an :ref:`Error` different from :ref:`@GlobalScope.OK` is returned). .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_set_remote_description: .. rst-class:: classref-method :ref:`Error` **set_remote_description** **(** :ref:`String` type, :ref:`String` sdp **)** 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 :ref:`session_description_created` with the appropriate answer. If ``type`` is ``answer`` the peer will start emitting :ref:`ice_candidate_created`. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`