RTCPeerConnection: метод addIceCandidate()

Метод addIceCandidate() интерфейса RTCPeerConnection добавляет новый удалённый кандидат в удалённое описание соединения, которое описывает состояние удалённого конца соединения.

Когда веб-сайт или приложение, использующее RTCPeerConnection, получает нового кандидата ICE от удалённого узла через канал сигнализации, оно передает полученного кандидата агенту ICE браузера, вызвав RTCPeerConnection.addIceCandidate(). Это добавляет этого нового удалённого кандидата в удалённое описание RTCPeerConnection, которое описывает состояние удалённого конца соединения.

Если параметр candidate отсутствует или при вызове addIceCandidate() задано значение null, добавляемый кандидат ICE является индикатором «конец кандидатов». То же самое происходит, если значение свойства candidate указанного объекта отсутствует или является пустой строкой (""), что сигнализирует о том, что все удалённые кандидаты были доставлены.

Уведомление об окончании кандидатов передаётся удалённому узлу с помощью кандидата со значением атрибута a-line end-of-candidates.

Во время переговоров ваше приложение, вероятно, получит множество кандидатов, которые вы передадите агенту ICE таким образом, чтобы он мог построить список потенциальных способов соединения. Подробное описание этого процесса можно найти в статьях Подключение WebRTC и Сигнализация и видеозвонки.

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

Объект RTCIceCandidate или объект со следующими свойствами:

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

Строка, описывающая свойства кандидата, взятая непосредственно из атрибута SDP "candidate". Строка кандидата указывает информацию о сетевом соединении для кандидата. Если candidate пустая строка (""), достигнут конец списка кандидатов; такой кандидат известен как маркер «конец кандидатов».

Синтаксис строки кандидата описан в RFC 5245, раздел 15.1. Для a-строки (строки атрибутов), которая выглядит так:

a=candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host

соответствующее значение строки candidate будет:

"candidate:4234997325 1 udp 2043278322 192.0.2.172 44323 typ host"`

Броузер всегда отдаёт предпочтение кандидатам с наивысшим priority, при прочих равных условиях. В приведенном выше примере приоритет равен 2043278322. Все атрибуты разделены одним пробелом и расположены в определённом порядке. Полный список атрибутов для этого кандидата:

• foundation = 4234997325
• component = "rtp" (число 1 закодировано в этой строке; 2 становится "rtcp")
• protocol = "udp"
• priority = 2043278322
• ip = "192.0.2.172"
• port = 44323
• type = "host"

Дополнительную информацию можно найти в RTCIceCandidate.candidate.

Примечание: Для обратной совместимости со старыми версиями спецификации WebRTC конструктор также принимает эту строку напрямую в качестве аргумента.

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

Строка, содержащая идентификатор тега потока медиа, к которому относится кандидат, или null если нет связанного потока медиа. Значение по умолчанию — null.

Дополнительную информацию можно найти в RTCIceCandidate.sdpMid.

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

Числовое свойство, содержащее индекс m-строки (с нуля) с которой связан кандидат, в SDP описания медиа, или null если нет такой ассоциации. Значение по умолчанию — null.

Дополнительную информацию можно найти в RTCIceCandidate.sdpMLineIndex.

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

Строка, содержащая фрагмент имени пользователя (обычно сокращённо «ufrag» или «ice-ufrag»). Этот фрагмент вместе с паролем ICE («ice-pwd») уникально идентифицирует одно текущее взаимодействие ICE (включая любое взаимодействие с сервером STUN).

Строка генерируется WebRTC в начале сеанса. Она может содержать до 256 символов, и по крайней мере 24 бита должны содержать случайные данные. У неё нет значения по умолчанию и она не присутствует, если не задана явно.

Дополнительную информацию можно найти в RTCIceCandidate.usernameFragment.

Метод бросит исключение TypeError, если и sdpMid и sdpMLineIndex имеют значение null.

Содержимое объекта должно быть построено из сообщения, полученного по каналу сигнализации, описывающего только что полученного кандидата ICE, готового к передаче локальному агенту ICE.

Если объект candidate не указан или его значение равно null, сигнал об окончании кандидатов отправляется удалённому узлу с помощью a-строки end-of-candidates в формате:

a=end-of-candidates

В старом коде и документации вы можете увидеть версию этой функции с обратной связью по вызовам. Она устарела и её использование **настоятельно не рекомендуется**. Вы должны обновить любой существующий код, чтобы использовать версию addIceCandidate() на основе Promise вместо этого. Параметры для старой формы addIceCandidate() описаны ниже, чтобы помочь в обновлении существующего кода.

successCallback Устарело

Функция, которая вызывается, когда кандидат ICE был успешно добавлен. Эта функция не принимает входных параметров и не возвращает значение.

failureCallback Устарело

Функция, которая вызывается, если попытка добавить кандидата ICE завершилась ошибкой. Принимает в качестве входного параметра объект DOMException, описывающий причину ошибки.

Объект Promise, который выполняется, когда кандидат был успешно добавлен в описание удалённого узла агентом ICE. Обещание не принимает никаких входных параметров.

При возникновении ошибки при попытке добавить ICE-кандидата, Promise, возвращаемый этим методом, отклоняется, возвращая одну из нижеприведённых ошибок в качестве атрибута name в указанном объекте DOMException, переданном обработчику отклонения.

TypeError

Возвращается, если у указанного кандидата атрибуты sdpMid и sdpMLineIndex оба равны null.

InvalidStateError DOMException

Возвращается, если у RTCPeerConnection в данный момент нет установленного удалённого пэра (remoteDescription равен null).

OperationError DOMException

Возвращается в одном из следующих случаев:

• Значение, указанное для sdpMid, не является null и не совпадает с идентификатором описания медиаданных ни одного из описаний медиаданных, включённых в remoteDescription.
• Указанное значение sdpMLineIndex больше или равно количеству описаний медиаданных, включённых в удалённое описание.
• Указанный ufrag не совпадает с полем ufrag в любом из рассматриваемых удалённых описаний.
• Одно или несколько значений в строке candidate являются недопустимыми или не могут быть обработаны.
• Попытка добавить кандидата по каким-либо причинам терпит неудачу.

Этот фрагмент кода демонстрирует, как передавать ICE-кандидатов через произвольный канал сигнализации.

// This example assumes that the other peer is using a signaling channel as follows:
//
// pc.onicecandidate = (event) => {
//   if (event.candidate) {
//     signalingChannel.send(JSON.stringify({ice: event.candidate})); // "ice" is arbitrary
//   } else {
//     // All ICE candidates have been sent
//   }
// }

signalingChannel.onmessage = (receivedString) => {
  const message = JSON.parse(receivedString);
  if (message.ice) {
    // A typical value of ice here might look something like this:
    //
    // {candidate: "candidate:0 1 UDP 2122154243 192.0.2.43 53421 typ host", sdpMid: "0", …}
    //
    // Pass the whole thing to addIceCandidate:

    pc.addIceCandidate(message.ice).catch((e) => {
      console.log(`Failure during addIceCandidate(): ${e.name}`);
    });
  } else {
    // handle other things you might be signaling, like sdp
  }
};

Последний кандидат, переданный таким образом удалённым пэром, будет специальным кандидатом, обозначающим конец списка кандидатов. Для наглядности, конец списка кандидатов может быть указан вручную следующим образом:

pc.addIceCandidate({ candidate: "" });

Однако, в большинстве случаев вам не нужно будет явно искать это, так как события, управляющие RTCPeerConnection, будут обрабатывать это за вас, отправляя соответствующие события.

• API WebRTC
• Сигнализация и видеозвонки
• Введение в протоколы WebRTC
• Подключение WebRTC
• Продолжительность сеанса WebRTC