RTCPeerConnection: метод setLocalDescription()

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

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

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

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

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

Строка, указывающая тип описания сессии. Если вы не укажете описание сессии явно, среда выполнения WebRTC попытается обработать его корректно. Если состояние сигнализации — одно из stable, have-local-offer, или have-remote-pranswer, среда выполнения WebRTC автоматически создаёт новое предложение и устанавливает его в качестве нового локального описания. В противном случае, setLocalDescription() создаёт ответ, который становится новым локальным описанием.

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

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

Если описание опущено, среда выполнения WebRTC пытается автоматически сделать правильный выбор.

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

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

successCallback Устарело

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

errorCallback Устарело

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

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

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

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

InvalidStateError DOMException Устарело

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

InvalidSessionDescriptionError DOMException Устарело

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

Одно из преимуществ параметризованной формы setLocalDescription() заключается в том, что она значительно упрощает код переговоров. Это примерно то, что должен выглядеть ваш обработчик события negotiationneeded. Добавьте код сервера сигнализации, который здесь представлен вызовом signalRemotePeer().

pc.addEventListener("negotiationneeded", async (event) => {
  await pc.setLocalDescription();
  signalRemotePeer({ description: pc.localDescription });
});

Помимо обработки ошибок, всё!

В примере ниже показана реализация обработчика события negotiationneeded, которая явно создаёт предложение, а не позволяет setLocalDescription() сделать это.

async function handleNegotiationNeededEvent() {
  try {
    const offer = await pc.createOffer();
    pc.setLocalDescription(offer);
    signalRemotePeer({ description: pc.localDescription });
  } catch (err) {
    window.reportError(err);
  }
}

Он начинается с создания предложения с помощью вызова createOffer(); после успешного выполнения вызывается setLocalDescription(). Затем мы можем отправить созданное предложение другому узлу с помощью сервера сигнализации, что здесь выполняется с помощью функции под названием signalRemotePeer().

• API WebRTC
• RTCSessionDescription