RTCPeerConnection: событие icecandidate

Событие icecandidate отправляется в RTCPeerConnection, когда:

• Кандидат RTCIceCandidate был идентифицирован и добавлен к локальному peer при вызове RTCPeerConnection.setLocalDescription(),
• Каждый RTCIceCandidate, связанный с конкретным фрагментом имени пользователя и комбинацией паролей (поколение), был так идентифицирован и добавлен, и
• Сбор ICE на всех каналах завершён.

В первых двух случаях обработчик событий должен передать кандидата удалённому peer по каналу сигнализации, чтобы удалённый peer смог добавить его в свой набор удалённых кандидатов.

Это событие не может быть отменено и не «пузырится».

Используйте имя события в методах, таких как addEventListener(), или установите обработчик событий.

addEventListener("icecandidate", (event) => {});

onicecandidate = (event) => {};

RTCPeerConnectionIceEvent. Наследуется от Event.

Так как RTCPeerConnectionIceEvent является Event, это событие также реализует следующие свойства.

RTCPeerConnectionIceEvent.candidate Только для чтения

Указывает RTCIceCandidate, содержащий кандидата, связанного с событием. Будет пустой строкой, если событие указывает, что больше кандидатов в этом поколении нет, или null если сбор ICE на всех каналах завершён.

Событие icecandidate на RTCPeerConnection срабатывает по трём причинам.

Большинство событий icecandidate срабатывают, чтобы указать, что новый кандидат был собран. Этот кандидат должен быть передан удалённому peer по каналу сигнализации, управляемому вашим кодом.

rtcPeerConnection.onicecandidate = (event) => {
  if (event.candidate !== null) {
    sendCandidateToRemotePeer(event.candidate);
  } else {
    /* there are no more candidates coming during this negotiation */
  }
};

Удалённый peer, получив кандидата, добавит его в свой пул кандидатов, вызвав addIceCandidate() и передав строку candidate, переданную вами через сервер сигнализации.

Когда сессия ICE-переговоров исчерпывает кандидатов для данного RTCIceTransport, сбор для поколения кандидатов завершается. Об этом сигнализирует событие icecandidate с пустой строкой candidate ("").

Вы должны передать это удалённому peer так же, как и стандартного кандидата, как описано в разделе Передача нового кандидата выше. Это гарантирует, что удалённому peer также будет сообщено об окончании кандидатов. Как видно из кода в предыдущем разделе, каждый кандидат отправляется другому peer, включая тех, у кого может быть пустая строка кандидата. Только кандидаты, для которых свойство candidate события является null, не передаются по каналу сигнализации.

Об указании окончания кандидатов говорится в разделе 9.3 черновика спецификации Trickle ICE (обратите внимание, что номер раздела может измениться, пока спецификация проходит многократные этапы разработки).

После того, как все каналы ICE завершат сбор кандидатов, и значение свойства RTCPeerConnection объекта iceGatheringState перейдёт в состояние complete, отправляется событие icecandidate со значением candidate равным null.

Этот сигнал существует для обеспечения обратной совместимости и не должен передаваться удалённому peer (поэтому фрагмент кода выше проверяет, является ли event.candidate равным null перед отправкой кандидата).

Если вам нужно выполнить какие-либо особые действия, когда больше кандидатов не ожидается, гораздо лучше следить за состоянием сбора ICE, отслеживая события icegatheringstatechange:

pc.addEventListener("icegatheringstatechange", (ev) => {
  switch (pc.iceGatheringState) {
    case "new":
      /* gathering is either just starting or has been reset */
      break;
    case "gathering":
      /* gathering has begun or is ongoing */
      break;
    case "complete":
      /* gathering has ended */
      break;
  }
});

Как видно из этого примера, событие icegatheringstatechange сообщает вам, когда значение свойства RTCPeerConnection iceGatheringState было обновлено. Если это значение теперь complete, вы знаете, что сбор ICE только что завершился.

Это более надёжный подход, чем поиск отдельных сообщений ICE, указывающих на окончание сессии ICE.

В этом примере создаётся простой обработчик события icecandidate, который использует функцию sendMessage() для создания и отправки ответа удалённому peer через сервер сигнализации.

Сначала пример с использованием addEventListener():

pc.addEventListener(
  "icecandidate",
  (ev) => {
    if (ev.candidate !== null) {
      sendMessage({
        type: "new-ice-candidate",
        candidate: ev.candidate,
      });
    }
  },
  false,
);

Вы также можете установить обработчик события onicecandidate напрямую:

pc.onicecandidate = (ev) => {
  if (ev.candidate !== null) {
    sendMessage({
      type: "new-ice-candidate",
      candidate: ev.candidate,
    });
  }
};

• API WebRTC
• Сигнализация и видеозвонки