RTCPeerConnection: метод setRemoteDescription()

Метод setRemoteDescription() интерфейса RTCPeerConnection устанавливает указанное описание сессии в качестве текущего предложения или ответа удалённого участника. Описание определяет свойства удалённого конца соединения, включая формат медиа. Метод принимает единственный параметр — описание сессии — и возвращает Promise, который выполняется после асинхронного изменения описания.

Обычно этот метод вызывается после получения предложения или ответа от другого участника через сервер сигнализации. Имейте в виду, что если setRemoteDescription() вызывается, когда соединение уже установлено, это означает, что идёт переподключение (возможно, для адаптации к меняющимся условиям сети).

Поскольку описания обмениваются до тех пор, пока два участника не согласятся на конфигурацию, описание, переданное при вызове setRemoteDescription(), не вступает в силу сразу. Вместо этого текущая конфигурация соединения остаётся неизменной до завершения переговоров. Только тогда согласованная конфигурация вступает в силу.

sessionDescription

Объект, определяющий текущее предложение или ответ удалённого участника. Он должен содержать следующие свойства:

type

Строка, указывающая тип описания сессии. См. RTCSessionDescription.type.

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

Строка, содержащая SDP, описывающая сессию. Если sdp не указан, он по умолчанию пустой. Если type является "rollback", sdp должно быть null или пустой строкой. См. RTCSessionDescription.sdp.

Вы также можете передать экземпляр RTCSessionDescription, но разницы нет. По этой причине конструктор RTCSessionDescription устарел.

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

successCallback Устарел

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

errorCallback Устарел

Функция с сигнатурой RTCPeerConnectionErrorCallback, которая вызывается, если описание не может быть установлено. Ей передаётся единственный объект DOMException, объясняющий причину неудачи.

Эта устаревшая форма метода возвращает значение мгновенно, не дожидаясь фактического выполнения операции: в случае успеха вызывается successCallback; в случае неудачи — errorCallback.

A Promise, который выполняется, когда значение remoteDescription соединения успешно изменено или отклоняется, если изменение не может быть применено (например, если указанное описание несовместимо с одним или обоими участниками соединения). Обработчик выполнения обещания не принимает входных параметров.

Следующие исключения сообщаются обработчику отклонения обещания, возвращаемого setRemoteDescription():

InvalidAccessError DOMException

Возвращается, если содержимое описания некорректно.

InvalidStateError DOMException

Возвращается, если RTCPeerConnection закрыто или находится в состоянии, несовместимом с типом type указанного описания. Например, это исключение выбрасывается, если type является rollback, а состояние сигнализации — stable, have-local-pranswer или have-remote-pranswer, потому что вы не можете откатить соединение, которое либо полностью установлено, либо находится на заключительной стадии подключения.

OperationError DOMException

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

RTCError DOMException

Возвращается с установленным errorDetail в sdp-syntax-error, если SDP, указанный в RTCSessionDescription.sdp, недействителен. Свойство sdpLineNumber объекта ошибки указывает номер строки в SDP, где была обнаружена синтаксическая ошибка.

TypeError

Возвращается, если sessionDescription отсутствует свойство type или вообще не был передан ни один параметр описания.

При использовании устаревшей версии метода setRemoteDescription() с обратными вызовами могут возникнуть следующие исключения:

InvalidStateError Устарел

Состояние сигнализации signalingState соединения равно "closed", что указывает на то, что соединение в настоящее время не открыто, поэтому переговоры не могут быть проведены.

InvalidSessionDescriptionError Устарел

Параметр sessionDescription некорректен.

При вызове setRemoteDescription(), агент ICE проверяет, находится ли RTCPeerConnection в состоянии stable или have-remote-offer signalingState. Эти состояния означают, что либо существующее соединение переподключается, либо предложение, ранее указанное в предыдущем вызове setRemoteDescription(), заменяется новым предложением. В обоих этих случаях мы находимся в начале процесса переговоров, и предложение устанавливается как удалённое описание.

С другой стороны, если мы находимся в середине текущих переговоров и в setRemoteDescription() передаётся предложение, агент ICE автоматически начинает откат ICE, чтобы вернуть соединение в стабильное состояние сигнализации, а затем, после завершения отката, устанавливает удалённое описание в указанное предложение. Это запускает новую сессию переговоров, с новым предложением в качестве отправной точки.

После начала новых переговоров с установленным предложением локальный участник теперь является получателем, даже если он ранее был инициатором. Это происходит вместо выдачи исключения, тем самым уменьшая количество возможных ошибок и упрощая обработку, которую вам нужно выполнить при получении предложения, исключив необходимость обрабатывать процесс предложения/ответа по-разному в зависимости от того, является ли локальный участник инициатором или получателем.

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

function handleOffer(msg) {
  createMyPeerConnection();

  myPeerConnection
    .setRemoteDescription(msg.description)
    .then(() => navigator.mediaDevices.getUserMedia(mediaConstraints))
    .then((stream) => {
      document.getElementById("local_video").srcObject = stream;
      return myPeerConnection.addStream(stream);
    })
    .then(() => myPeerConnection.createAnswer())
    .then((answer) => myPeerConnection.setLocalDescription(answer))
    .then(() => {
      // Send the answer to the remote peer using the signaling server
    })
    .catch(handleGetUserMediaError);
}

После создания нашего RTCPeerConnection и сохранения его как myPeerConnection, мы передаём описание, содержащееся в полученном сообщении с предложением, msg, непосредственно в setRemoteDescription() для того, чтобы сообщить веб-слою WebRTC пользователя о предложенной настройке вызывающей стороны. Когда вызывается обработчик выполнения обещания, указывающий на то, что это сделано, мы создаём поток, добавляем его к соединению, затем создаём ответ SDP и вызываем setLocalDescription() для установки этой конфигурации с нашей стороны вызова перед передачей этого ответа вызывающей стороне.

• WebRTC
• RTCPeerConnection.remoteDescription, RTCPeerConnection.pendingRemoteDescription, RTCPeerConnection.currentRemoteDescription
• RTCSessionDescription