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-кандидатами друг с другом.

После этих шагов соединение должно быть установлено. Подробности см. в связанных руководствах.

Обучающие материалы

• Документация WebRTC

• Высокоуровневый мультиплеер

Методы

Error	add_ice_candidate(media: String, index: int, name: String)
void	close()
WebRTCDataChannel	create_data_channel(label: String, options: Dictionary = {})
Error	create_offer()
ConnectionState	get_connection_state() const
GatheringState	get_gathering_state() const
SignalingState	get_signaling_state() const
Error	initialize(configuration: Dictionary = {})
Error	poll()
void	set_default_extension(extension_class: StringName) static
Error	set_local_description(type: String, sdp: String)
Error	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

WebRTC PeerConnection было закрыто.

---

Описания метода

Error add_ice_candidate(media: String, index: int, name: String) 🔗

Добавьте кандидата ice, сгенерированного удаленным пиром (и полученного через сервер сигнализации). См. ice_candidate_created.

---

void close() 🔗

Закройте одноранговое соединение и все каналы данных, связанные с ним.

Примечание: Вы не сможете повторно использовать этот объект для нового соединения, если не вызовете initialize().

---

WebRTCDataChannel create_data_channel(label: String, options: Dictionary = {}) 🔗

Возвращает новый WebRTCDataChannel (или null при неудаче) с заданной label и опционально настроенным через словарь options. Этот метод может быть вызван только тогда, когда соединение находится в состоянии STATE_NEW.

Существует два способа создания рабочего канала данных: либо вызвать create_data_channel() только на одном из одноранговых узлов и прослушивать data_channel_received на другом, либо вызвать create_data_channel() на обоих одноранговых узлах с одинаковыми значениями и параметром "negotiated", установленным на true.

Допустимые options:

{
    "negotiated": true, # Если установлено значение true (по умолчанию отключено), это означает, что канал согласовывается вне диапазона. Также необходимо задать «id». «data_channel_received» не будет вызываться.
    "id": 1, # Если «negotiated» имеет значение true, это значение также должно быть установлено на одно и то же значение на обоих одноранговых узлах.

    # Можно указать только один из maxRetransmits и maxPacketLifeTime, но не оба. Они делают канал ненадежным (но также лучше в реальном времени).
    "maxRetransmits": 1, # Укажите максимальное количество попыток, которые одноранговый узел предпримет для повторной передачи пакетов, если они не подтверждены.
    "maxPacketLifeTime": 100, # Укажите максимальный промежуток времени до прекращения повторной передачи неподтвержденных пакетов (в миллисекундах).
    "ordered": true, # В ненадежном режиме (т. е. установлено либо «maxRetransmits», либо «maxPacketLifetime») «ordered» (по умолчанию true) указывает, следует ли принудительно применять упорядочивание пакетов.

    "protocol": "my-custom-protocol", # Пользовательская строка под-протокола для этого канала.
}

Примечание: Вы должны сохранить ссылку на каналы, созданные таким образом, иначе они будут закрыты.

---

Error create_offer() 🔗

Создает новое предложение 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" ], # Один или несколько STUN-серверов.
            "username": "a_username", # Необязательное имя пользователя для сервера TURN.
            "credential": "a_password", # Необязательное имя пользователя для сервера TURN.
        }
    ]
}

---

Error poll() 🔗

Чаще вызывайте этот метод (например, в Node._process() или Node._physics_process()) для правильного приема сигналов.

---

void set_default_extension(extension_class: StringName) static 🔗

Устанавливает extension_class в качестве WebRTCPeerConnectionExtension по умолчанию, возвращаемого при создании нового WebRTCPeerConnection.

---

Error set_local_description(type: String, sdp: String) 🔗

Устанавливает описание SDP локального однорангового узла. Это должно быть вызвано в ответ на session_description_created.

После вызова этой функции одноранговый узел начнет выдавать ice_candidate_created (если только не будет возвращено Error, отличное от @GlobalScope.OK).

---

Error set_remote_description(type: String, sdp: String) 🔗

Устанавливает описание SDP удаленного пира. Это должно быть вызвано со значениями, сгенерированными удаленным пиром и полученными через сервер сигнализации.

Если type — "offer", то пир выдаст session_description_created с соответствующим ответом.

Если type — "answer", то пир начнет выдавать ice_candidate_created.