:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/master/modules/webrtc/doc_classes/WebRTCPeerConnection.xml. .. _class_WebRTCPeerConnection: WebRTCPeerConnection ==================== **Inherits:** :ref:`RefCounted` **<** :ref:`Object` **Inherited By:** :ref:`WebRTCPeerConnectionExtension` 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 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`\ (\ media\: :ref:`String`, index\: :ref:`int`, name\: :ref:`String`\ ) | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`close`\ (\ ) | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`WebRTCDataChannel` | :ref:`create_data_channel`\ (\ label\: :ref:`String`, options\: :ref:`Dictionary` = {}\ ) | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`create_offer`\ (\ ) | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`ConnectionState` | :ref:`get_connection_state`\ (\ ) |const| | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`GatheringState` | :ref:`get_gathering_state`\ (\ ) |const| | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`SignalingState` | :ref:`get_signaling_state`\ (\ ) |const| | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`initialize`\ (\ configuration\: :ref:`Dictionary` = {}\ ) | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`poll`\ (\ ) | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_default_extension`\ (\ extension_class\: :ref:`StringName`\ ) |static| | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`set_local_description`\ (\ type\: :ref:`String`, sdp\: :ref:`String`\ ) | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`set_remote_description`\ (\ type\: :ref:`String`, sdp\: :ref:`String`\ ) | +-------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Signals ------- .. _class_WebRTCPeerConnection_signal_data_channel_received: .. rst-class:: classref-signal **data_channel_received**\ (\ channel\: :ref:`WebRTCDataChannel`\ ) :ref:`🔗` 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**\ (\ media\: :ref:`String`, index\: :ref:`int`, name\: :ref:`String`\ ) :ref:`🔗` 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**\ (\ type\: :ref:`String`, sdp\: :ref:`String`\ ) :ref:`🔗` 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**: :ref:`🔗` .. _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-item-separator ---- .. _enum_WebRTCPeerConnection_GatheringState: .. rst-class:: classref-enumeration enum **GatheringState**: :ref:`🔗` .. _class_WebRTCPeerConnection_constant_GATHERING_STATE_NEW: .. rst-class:: classref-enumeration-constant :ref:`GatheringState` **GATHERING_STATE_NEW** = ``0`` The peer connection was just created and hasn't done any networking yet. .. _class_WebRTCPeerConnection_constant_GATHERING_STATE_GATHERING: .. rst-class:: classref-enumeration-constant :ref:`GatheringState` **GATHERING_STATE_GATHERING** = ``1`` The ICE agent is in the process of gathering candidates for the connection. .. _class_WebRTCPeerConnection_constant_GATHERING_STATE_COMPLETE: .. rst-class:: classref-enumeration-constant :ref:`GatheringState` **GATHERING_STATE_COMPLETE** = ``2`` The ICE agent has finished gathering candidates. If something happens that requires collecting new candidates, such as a new interface being added or the addition of a new ICE server, the state will revert to gathering to gather those candidates. .. rst-class:: classref-item-separator ---- .. _enum_WebRTCPeerConnection_SignalingState: .. rst-class:: classref-enumeration enum **SignalingState**: :ref:`🔗` .. _class_WebRTCPeerConnection_constant_SIGNALING_STATE_STABLE: .. rst-class:: classref-enumeration-constant :ref:`SignalingState` **SIGNALING_STATE_STABLE** = ``0`` There is no ongoing exchange of offer and answer underway. This may mean that the **WebRTCPeerConnection** is new (:ref:`STATE_NEW`) or that negotiation is complete and a connection has been established (:ref:`STATE_CONNECTED`). .. _class_WebRTCPeerConnection_constant_SIGNALING_STATE_HAVE_LOCAL_OFFER: .. rst-class:: classref-enumeration-constant :ref:`SignalingState` **SIGNALING_STATE_HAVE_LOCAL_OFFER** = ``1`` The local peer has called :ref:`set_local_description`, passing in SDP representing an offer (usually created by calling :ref:`create_offer`), and the offer has been applied successfully. .. _class_WebRTCPeerConnection_constant_SIGNALING_STATE_HAVE_REMOTE_OFFER: .. rst-class:: classref-enumeration-constant :ref:`SignalingState` **SIGNALING_STATE_HAVE_REMOTE_OFFER** = ``2`` The remote peer has created an offer and used the signaling server to deliver it to the local peer, which has set the offer as the remote description by calling :ref:`set_remote_description`. .. _class_WebRTCPeerConnection_constant_SIGNALING_STATE_HAVE_LOCAL_PRANSWER: .. rst-class:: classref-enumeration-constant :ref:`SignalingState` **SIGNALING_STATE_HAVE_LOCAL_PRANSWER** = ``3`` The offer sent by the remote peer has been applied and an answer has been created and applied by calling :ref:`set_local_description`. This provisional answer describes the supported media formats and so forth, but may not have a complete set of ICE candidates included. Further candidates will be delivered separately later. .. _class_WebRTCPeerConnection_constant_SIGNALING_STATE_HAVE_REMOTE_PRANSWER: .. rst-class:: classref-enumeration-constant :ref:`SignalingState` **SIGNALING_STATE_HAVE_REMOTE_PRANSWER** = ``4`` A provisional answer has been received and successfully applied in response to an offer previously sent and established by calling :ref:`set_local_description`. .. _class_WebRTCPeerConnection_constant_SIGNALING_STATE_CLOSED: .. rst-class:: classref-enumeration-constant :ref:`SignalingState` **SIGNALING_STATE_CLOSED** = ``5`` The **WebRTCPeerConnection** has been closed. .. 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**\ (\ media\: :ref:`String`, index\: :ref:`int`, name\: :ref:`String`\ ) :ref:`🔗` 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**\ (\ ) :ref:`🔗` 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**\ (\ label\: :ref:`String`, options\: :ref:`Dictionary` = {}\ ) :ref:`🔗` 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**\ (\ ) :ref:`🔗` 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| :ref:`🔗` Returns the connection state. See :ref:`ConnectionState`. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_get_gathering_state: .. rst-class:: classref-method :ref:`GatheringState` **get_gathering_state**\ (\ ) |const| :ref:`🔗` Returns the ICE :ref:`GatheringState` of the connection. This lets you detect, for example, when collection of ICE candidates has finished. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_get_signaling_state: .. rst-class:: classref-method :ref:`SignalingState` **get_signaling_state**\ (\ ) |const| :ref:`🔗` Returns the signaling state on the local end of the connection while connecting or reconnecting to another peer. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_initialize: .. rst-class:: classref-method :ref:`Error` **initialize**\ (\ configuration\: :ref:`Dictionary` = {}\ ) :ref:`🔗` Re-initialize this peer connection, closing any previously active connection, and going back to state :ref:`STATE_NEW`. A dictionary of ``configuration`` options can be passed to configure the peer connection. Valid ``configuration`` 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**\ (\ ) :ref:`🔗` 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_default_extension: .. rst-class:: classref-method |void| **set_default_extension**\ (\ extension_class\: :ref:`StringName`\ ) |static| :ref:`🔗` Sets the ``extension_class`` as the default :ref:`WebRTCPeerConnectionExtension` returned when creating a new **WebRTCPeerConnection**. .. rst-class:: classref-item-separator ---- .. _class_WebRTCPeerConnection_method_set_local_description: .. rst-class:: classref-method :ref:`Error` **set_local_description**\ (\ type\: :ref:`String`, sdp\: :ref:`String`\ ) :ref:`🔗` 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**\ (\ type\: :ref:`String`, sdp\: :ref:`String`\ ) :ref:`🔗` 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.)` .. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` .. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` .. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` .. |void| replace:: :abbr:`void (No return value.)`