RTCPeerConnection: метод createDataChannel()

Метод createDataChannel() интерфейса RTCPeerConnection создаёт новый канал, связанный с удалённым участником, по которому можно передавать любые типы данных. Это может быть полезно для передачи дополнительного контента, такого как изображения, файлы, текстовые сообщения, пакеты обновлений игр и так далее.

Если новый канал данных является первым, добавленным в соединение, переустановление связи запускается путём передачи события negotiationneeded.

label

Наименование канала, понятное для человека. Эта строка не может быть длиннее 65 535 байтов.

options Необязательно

Объект, содержащий конфигурационные параметры канала данных. Он может содержать следующие поля:

ordered Необязательно

Указывает, обязаны ли сообщения, отправленные по RTCDataChannel, прийти к месту назначения в том же порядке, в котором они были отправлены (true), или им разрешено приходить в произвольном порядке (false). true

maxPacketLifeTime Необязательно

Максимальное время в миллисекундах, которое может потребоваться для попытки передачи сообщения в ненадежном режиме. Хотя это значение является 16-битным беззнаковым числом, каждый пользовательский агент может ограничить его любым максимальным значением, которое он сочтёт уместным. null

maxRetransmits Необязательно

Максимальное количество попыток повторной передачи сообщения пользователем, которое не удалось с первого раза, в ненадежном режиме. Хотя это значение является 16-битным беззнаковым числом, каждый пользовательский агент может ограничить его любым максимальным значением, которое он сочтёт уместным. null

protocol Необязательно

Имя подпротокола, используемого в RTCDataChannel, если таковой имеется; в противном случае — пустая строка (""). "" Эта строка не может быть длиннее 65 535 байтов.

negotiated Необязательно

По умолчанию (false) каналы данных согласовываются по каналу, где одна сторона вызывает createDataChannel, а другая сторона прослушивает событие RTCDataChannelEvent с помощью обработчика события ondatachannel. В качестве альтернативы (true) они могут быть согласованы вне канала, где обе стороны вызывают createDataChannel с заранее согласованным идентификатором. false

id Необязательно

16-битный числовой идентификатор канала; допустимые значения — от 0 до 65 534. Если вы не укажете этот параметр, пользовательский агент выберет идентификатор за вас.

Новый объект RTCDataChannel с указанным label, настроенный с помощью параметров, указанных в options , если этот параметр включён; в противном случае устанавливаются значения по умолчанию, перечисленные выше.

InvalidStateError DOMException

Выбрасывается, если RTCPeerConnection закрыт.

TypeError

Выбрасывается в следующих ситуациях:

• Длина строки метки и/или протокола слишком велика; она не может быть больше 65 535 байтов (байты, а не символы).
• Значение id равно 65535. Хотя это допустимое беззнаковое 16-битное значение, оно не является допустимым значением для id.

SyntaxError DOMException

Выбрасывается, если значения были указаны для обоих параметров maxPacketLifeTime и maxRetransmits. Вы можете указать значение, отличное от null , только для одного из них.

ResourceInUse DOMException

Выбрасывается, если был указан id , но другой RTCDataChannel уже использует это же значение.

OperationError DOMException

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

В этом примере показано, как создать канал данных и настроить обработчики событий open и message для отправки и получения сообщений по нему (для краткости в примере предполагается, что onnegotiationneeded настроен).

// Offerer side

const pc = new RTCPeerConnection(options);
const channel = pc.createDataChannel("chat");
channel.onopen = (event) => {
  channel.send("Hi you!");
};
channel.onmessage = (event) => {
  console.log(event.data);
};

// Answerer side

const pc = new RTCPeerConnection(options);
pc.ondatachannel = (event) => {
  const channel = event.channel;
  channel.onopen = (event) => {
    channel.send("Hi back!");
  };
  channel.onmessage = (event) => {
    console.log(event.data);
  };
};

В качестве альтернативы можно использовать более симметричное согласование вне канала, используя согласованный идентификатор (0 здесь):

// Both sides

const pc = new RTCPeerConnection(options);
const channel = pc.createDataChannel("chat", { negotiated: true, id: 0 });
channel.onopen = (event) => {
  channel.send("Hi!");
};
channel.onmessage = (event) => {
  console.log(event.data);
};

Для более подробного примера, демонстрирующего, как создаётся соединение и канал, см. Пример использования RTCDataChannel.

• RTCDataChannel
• Пример использования RTCDataChannel
• RTCPeerConnection