WebRTCPeerConnection

Наследует: RefCounted < Object

Наследуется от: WebRTCPeerConnectionExtension

Интерфейс для однорангового пир соединения WebRTC.

Описание

Соединение WebRTC между локальным компьютером и удаленным узлом. Предоставляет интерфейс для подключения, поддержания и мониторинга соединения.

Настройка соединения WebRTC между двумя узлами может показаться непростой задачей, но её можно разбить на 3 основных шага:

  • Узел, желающий инициировать соединение (далее A), создает предложение и отправляет его другому узлу (далее B).

  • B получает предложение, генерирует ответ и отправляет его A.

  • Затем A и B генерируют и обмениваются ICE-кандидатами друг с другом.

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

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

Методы

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.