Простой пример RTCDataChannel - Интерфейсы веб API

Простой пример RTCDataChannel
=============================

Интерфейс `RTCDataChannel` (en-US) является функциональностью WebRTC API , который позволяет открыть канал между узлами соединения, по которому можно отправлять и получать произвольные данные. Эти API намеренно сходны с WebSocket API (en-US), для использования единой программной модели.

В этом примере мы откроем соединение `RTCDataChannel` (en-US), связывающее два элемента на одной странице. Хотя это явно надуманный сценарий, он полезен для демонстрации последовательности соединения двух узлов. Мы расскажем о механизме выполнения соединения, передачи и получения данных, но оставим немного информации о поиске и подключении к удалённому компьютеру для другого примера.

Разметка HTML
-------------

Сначала быстро посмотрим на необходимую разметку HTML. В ней нет ничего сложного. В начале мы определяем пару кнопок, создающих и закрывающих соединение:

```html
<button id="connectButton" name="connectButton" class="buttonleft">
  Connect
</button>
<button
 id="disconnectButton"
 name="disconnectButton"
 class="buttonright"
 disabled>
  Disconnect
</button>
```

Затем, определяем блок, который содержит элемент управления ввода текста, в который пользователь печатает текст своего сообщения, предназначенного для отправки, по нажатию кнопки. Элемент `<div>` будет представлять первый узел в канале передачи (сторона отправителя).

```html
<div class="messagebox">
  <label for="message"
 >Enter a message:
    <input
 type="text"
 name="message"
 id="message"
 placeholder="Message text"
 inputmode="latin"
 size="60"
 maxlength="120"
 disabled />
  </label>
  <button id="sendButton" name="sendButton" class="buttonright" disabled>
    Send
  </button>
</div>
```

И наконец, небольшой блок, в который будем помещать получаемое сообщение. Элемент `<div>` будет представлять второй узел соединения (сторона получателя).

```html
<div class="messagebox" id="receivebox">
  <p>Messages received:</p>
</div>
```

Код JavaScript
--------------

While you can just look at the code itself on GitHub, below we'll review the parts of the code that do the heavy lifting.

The WebRTC API makes heavy use of `Promise`s. They make it very easy to chain the steps of the connection process together; if you haven't already read up on this functionality of ECMAScript 2015, you should read up on them. Similarly, this example uses arrow functions to simplify syntax.

### Starting up

When the script is run, we set up an `load (en-US)` event listener, so that once the page is fully loaded, our `startup()` function is called.

```js
function startup() {
  connectButton = document.getElementById("connectButton");
  disconnectButton = document.getElementById("disconnectButton");
  sendButton = document.getElementById("sendButton");
  messageInputBox = document.getElementById("message");
  receiveBox = document.getElementById("receivebox");

  // Set event listeners for user interface widgets

  connectButton.addEventListener("click", connectPeers, false);
  disconnectButton.addEventListener("click", disconnectPeers, false);
  sendButton.addEventListener("click", sendMessage, false);
}
```

This is quite straightforward. We grab references to all the page elements we'll need to access, then set `event listeners` (en-US) on the three buttons.

### Establishing a connection

When the user clicks the "Connect" button, the `connectPeers()` method is called. We're going to break this up and look at it a bit at a time, for clarity.

**Примечание:** Even though both ends of our connection will be on the same page, we're going to refer to the one that starts the connection as the "local" one, and to the other as the "remote" end.

#### Set up the local peer

```js
localConnection = new RTCPeerConnection();

sendChannel = localConnection.createDataChannel("sendChannel");
sendChannel.onopen = handleSendChannelStatusChange;
sendChannel.onclose = handleSendChannelStatusChange;
```

The first step is to create the "local" end of the connection. This is the peer that will send out the connection request. The next step is to create the `RTCDataChannel` (en-US) by calling `RTCPeerConnection.createDataChannel()` (en-US) and set up event listeners to monitor the channel so that we know when it's opened and closed (that is, when the channel is connected or disconnected within that peer connection).

It's important to keep in mind that each end of the channel has its own `RTCDataChannel` (en-US) object.

#### Set up the remote peer

```js
remoteConnection = new RTCPeerConnection();
remoteConnection.ondatachannel = receiveChannelCallback;
```

The remote end is set up similarly, except that we don't need to explicitly create an `RTCDataChannel` (en-US) ourselves, since we're going to be connected through the channel established above. Instead, we set up a `datachannel` event handler; this will be called when the data channel is opened; this handler will receive an `RTCDataChannel` object; you'll see this below.

#### Set up the ICE candidates

The next step is to set up each connection with ICE candidate listeners; these will be called when there's a new ICE candidate to tell the other side about.

**Примечание:** In a real-world scenario in which the two peers aren't running in the same context, the process is a bit more involved; each side provides, one at a time, a suggested way to connect (for example, UDP, UDP with a relay, TCP, etc.) by calling `RTCPeerConnection.addIceCandidate()` (en-US), and they go back and forth until agreement is reached. But here, we just accept the first offer on each side, since there's no actual networking involved.

```js
localConnection.onicecandidate = (e) =>
  !e.candidate ||
  remoteConnection.addIceCandidate(e.candidate).catch(handleAddCandidateError);

remoteConnection.onicecandidate = (e) =>
  !e.candidate ||
  localConnection.addIceCandidate(e.candidate).catch(handleAddCandidateError);
```

We configure each `RTCPeerConnection` to have an event handler for the `icecandidate` event.

#### Start the connection attempt

The last thing we need to do in order to begin connecting our peers is to create a connection offer.

```js
localConnection
  .createOffer()
  .then((offer) => localConnection.setLocalDescription(offer))
  .then(() =>
    remoteConnection.setRemoteDescription(localConnection.localDescription),
  )
  .then(() => remoteConnection.createAnswer())
  .then((answer) => remoteConnection.setLocalDescription(answer))
  .then(() =>
    localConnection.setRemoteDescription(remoteConnection.localDescription),
  )
  .catch(handleCreateDescriptionError);
```

Let's go through this line by line and decipher what it means.

1. First, we call `RTCPeerConnection.createOffer()` (en-US) method to create an SDP (Session Description Protocol) blob describing the connection we want to make. This method accepts, optionally, an object with constraints to be met for the connection to meet your needs, such as whether the connection should support audio, video, or both. In our simple example, we don't have any constraints.
2. If the offer is created successfully, we pass the blob along to the local connection's `RTCPeerConnection.setLocalDescription()` (en-US) method. This configures the local end of the connection.
3. The next step is to connect the local peer to the remote by telling the remote peer about it. This is done by calling `remoteConnection.``RTCPeerConnection.setRemoteDescription()` (en-US). Now the `remoteConnection` knows about the connection that's being built. In a real application, this would require a signaling server to exchange the description object.
4. That means it's time for the remote peer to reply. It does so by calling its `createAnswer()` (en-US) method. This generates a blob of SDP which describes the connection the remote peer is willing and able to establish. This configuration lies somewhere in the union of options that both peers can support.
5. Once the answer has been created, it's passed into the remoteConnection by calling `RTCPeerConnection.setLocalDescription()` (en-US). That establishes the remote's end of the connection (which, to the remote peer, is its local end. This stuff can be confusing, but you get used to it). Again, this would normally be exchanged through a signalling server.
6. Finally, the local connection's remote description is set to refer to the remote peer by calling localConnection's `RTCPeerConnection.setRemoteDescription()` (en-US).
7. The `catch()` calls a routine that handles any errors that occur.

**Примечание:** Once again, this process is not a real-world implementation; in normal usage, there's two chunks of code running on two machines, interacting and negotiating the connection. A side channel, commonly called a "signalling server," is usually used to exchange the description (which is in **application/sdp** form) between the two peers.

#### Handling successful peer connection

As each side of the peer-to-peer connection is successfully linked up, the corresponding `RTCPeerConnection`'s `icecandidate` event is fired. These handlers can do whatever's needed, but in this example, all we need to do is update the user interface:

```js
function handleLocalAddCandidateSuccess() {
  connectButton.disabled = true;
}

function handleRemoteAddCandidateSuccess() {
  disconnectButton.disabled = false;
}
```

The only thing we do here is disable the "Connect" button when the local peer is connected and enable the "Disconnect" button when the remote peer connects.

#### Connecting the data channel

Once the `RTCPeerConnection` is open, the `datachannel` event is sent to the remote to complete the process of opening the data channel; this invokes our `receiveChannelCallback()` method, which looks like this:

```js
function receiveChannelCallback(event) {
  receiveChannel = event.channel;
  receiveChannel.onmessage = handleReceiveMessage;
  receiveChannel.onopen = handleReceiveChannelStatusChange;
  receiveChannel.onclose = handleReceiveChannelStatusChange;
}
```

The `datachannel` event includes, in its channel property, a reference to a `RTCDataChannel` (en-US) representing the remote peer's end of the channel. This is saved, and we set up, on the channel, event listeners for the events we want to handle. Once this is done, our `handleReceiveMessage()` method will be called each time data is received by the remote peer, and the `handleReceiveChannelStatusChange()` method will be called any time the channel's connection state changes, so we can react when the channel is fully opened and when it's closed.

### Handling channel status changes

Both our local and remote peers use a single method to handle events indicating a change in the status of the channel's connection.

When the local peer experiences an open or close event, the `handleSendChannelStatusChange()` method is called:

```js
function handleSendChannelStatusChange(event) {
  if (sendChannel) {
    var state = sendChannel.readyState;

    if (state === "open") {
      messageInputBox.disabled = false;
      messageInputBox.focus();
      sendButton.disabled = false;
      disconnectButton.disabled = false;
      connectButton.disabled = true;
    } else {
      messageInputBox.disabled = true;
      sendButton.disabled = true;
      connectButton.disabled = false;
      disconnectButton.disabled = true;
    }
  }
}
```

If the channel's state has changed to "open", that indicates that we have finished establishing the link between the two peers. The user interface is updated correspondingly by enabling the text input box for the message to send, focusing the input box so that the user can immediately begin to type, enabling the "Send" and "Disconnect" buttons, now that they're usable, and disabling the "Connect" button, since it is not needed when the conneciton is open.

If the state has changed to "closed", the opposite set of actions occurs: the input box and "Send" button are disabled, the "Connect" button is enabled so that the user can open a new connection if they wish to do so, and the "Disconnect" button is disabled, since it's not useful when no connection exists.

Our example's remote peer, on the other hand, ignores the status change events, except for logging the event to the console:

```js
function handleReceiveChannelStatusChange(event) {
  if (receiveChannel) {
    console.log(
      "Receive channel's status has changed to " + receiveChannel.readyState,
    );
  }
}
```

The `handleReceiveChannelStatusChange()` method receives as an input parameter the event which occurred; this will be an `RTCDataChannelEvent` (en-US).

### Sending messages

When the user presses the "Send" button, the sendMessage() method we've established as the handler for the button's `click (en-US)` event is called. That method is simple enough:

```js
function sendMessage() {
  var message = messageInputBox.value;
  sendChannel.send(message);

  messageInputBox.value = "";
  messageInputBox.focus();
}
```

First, the text of the message is fetched from the input box's `value` attribute. This is then sent to the remote peer by calling `sendChannel.send()` (en-US). That's all there is to it! The rest of this method is just some user experience sugar — the input box is emptied and re-focused so the user can immediately begin typing another message.

### Receiving messages

When a "message" event occurs on the remote channel, our `handleReceiveMessage()` method is called as the event handler.

```js
function handleReceiveMessage(event) {
  var el = document.createElement("p");
  var txtNode = document.createTextNode(event.data);

  el.appendChild(txtNode);
  receiveBox.appendChild(el);
}
```

This method simply performs some basic DOM injection; it creates a new `<p>` (paragraph) element, then creates a new `Text` node containing the message text, which is received in the event's `data` property. This text node is appended as a child of the new element, which is then inserted into the `receiveBox` block, thereby causing it to draw in the browser window.

### Disconnecting the peers

When the user clicks the "Disconnect" button, the `disconnectPeers()` method previously set as that button's handler is called.

```js
function disconnectPeers() {
  // Close the RTCDataChannels if they're open.

  sendChannel.close();
  receiveChannel.close();

  // Close the RTCPeerConnections

  localConnection.close();
  remoteConnection.close();

  sendChannel = null;
  receiveChannel = null;
  localConnection = null;
  remoteConnection = null;

  // Update user interface elements

  connectButton.disabled = false;
  disconnectButton.disabled = true;
  sendButton.disabled = true;

  messageInputBox.value = "";
  messageInputBox.disabled = true;
}
```

This starts by closing each peer's `RTCDataChannel` (en-US), then, similarly, each `RTCPeerConnection`. Then all the saved references to these objects are set to `null` to avoid accidental reuse, and the user interface is updated to reflect the fact that the connection has been closed.

Следующие шаги
--------------

Попробуйте пример в деле и посмотрите на исходный код простого примера, доступный на GitHub.


Сигнализированные и видео вызов - Интерфейсы веб API

Сигнализированные и видео вызов
===============================

WebRTC позволяет обмениваться медиаданными между двумя устройствами напрямую (peer-to-peer) в режиме реального времени. Соединение устанавливается путём обнаружения и согласования, называемым **сигнализацией (signaling)**. Эта статья объясняет, как сделать двусторонний видеозвонок.

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

В этой статье мы будем дорабатывать WebSocket-чат, созданный для нашей документации к WebSocket, — добавим к нему двусторонний видеозвонок между двумя пользователями. Вы можете использовать этот пример на Glitch или клонировать его, чтобы поэкспериментировать самим. Весь проект можно посмотреть на GitHub.

**Примечание:** If you try out the example on Glitch, please note that any changes made to the code will immediately reset any connections. In addition, there is a short timeout period; the Glitch instance is for quick experiments and testing only.

Сервер сигнализации
-------------------

Для установление WebRTC-соединения между двумя устройствами необходим **сервер сигнализации**, чтобы определить, как соединять эти устройства через Интернет. Сервер сигнализации выступает посредником между пирами, позволяя им найти адреса друг друга и установить соединение, и предельно минимизирует риск утечки информации, которая может оказаться личной. Как создать такой сервер и как устроен процесс сигнализации?

Во-первых, нужен сам сервер сигнализации. Спецификация WebRTC не определяет, какой транспорт используется для передачи сигнальной информации. Можете использовать какой вам нравится, от WebSocket (en-US) до `XMLHttpRequest` и почтовых голубей, чтобы передать сигнальную информацию между пирами.

Важно, что серверу не нужно понимать или интерпретировать сигнальные данные. Хотя они в формате SDP, это не имеет особого значения: содержание сообщений, проходящих через сигнальный сервер - по сути, чёрный ящик. Значение имеет лишь то, что когда подсистема ICE (en-US) даёт команду передать данные другому пиру, вы просто это делаете, а уже пир знает, как получить эту информацию и доставить её на свою подсистему ICE. Все что нужно - передавать сообщения туда и обратно. Содержание совершенно не важно для сигнального сервера.

### Подготовка сервера чата к сигнализации

Наш сервер чата использует WebSocket API (en-US) для отправки информации как JSON между каждым клиентом и сервером. Сервер поддерживает несколько типов сообщений для нескольких задач : регистрация нового пользователя, установки имён пользователей, отправка сообщений чата.

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

Let's take a look which changes we need to make to the chat server support WebRTC signaling. This is in the file chatserver.js.

First up is the addition of the function `sendToOneUser()`. As the name suggests, this sends a stringified JSON message to a particular username.

```js
function sendToOneUser(target, msgString) {
  var isUnique = true;
  var i;

  for (i = 0; i < connectionArray.length; i++) {
    if (connectionArray[i].username === target) {
      connectionArray[i].send(msgString);
      break;
    }
  }
}
```

This function iterates over the list of connected users until it finds one matching the specified username, then sends the message to that user. The parameter `msgString` is a stringified JSON object. We could have made it receive our original message object, but in this example it's more efficient this way. Since the message has already been stringified, we can send it with no further processing. Each entry in `connectionArray` is a `WebSocket` object, so we can just call its `send()` (en-US) method directly.

Our original chat demo didn't support sending messages to a specific user. The next task is to update the main WebSocket message handler to support doing so. This involves a change near the end of the `"connection"` message handler:

```js
if (sendToClients) {
  var msgString = JSON.stringify(msg);
  var i;

  if (msg.target && msg.target !== undefined && msg.target.length !== 0) {
    sendToOneUser(msg.target, msgString);
  } else {
    for (i = 0; i < connectionArray.length; i++) {
      connectionArray[i].send(msgString);
    }
  }
}
```

This code now looks at the pending message to see if it has a `target` property. If that property is present, it specifies the username of the client to which the message is to be sent, and we call `sendToOneUser()` to send the message to them. Otherwise, the message is broadcast to all users by iterating over the connection list, sending the message to each user.

As the existing code allows the sending of arbitrary message types, no additional changes are required. Our clients can now send messages of unknown types to any specific user, letting them send signaling messages back and forth as desired.

That's all we need to change on the server side of the equation. Now let's consider the signaling protocol we will implement.

### Designing the signaling protocol

Now that we've built a mechanism for exchanging messages, we need a protocol defining how those messages will look. This can be done in a number of ways; what's demonstrated here is just one possible way to structure signaling messages.

This example's server uses stringified JSON objects to communicate with its clients. This means our signaling messages will be in JSON format, with contents which specify what kind of messages they are as well as any additional information needed in order to handle the messages properly.

#### Exchanging session descriptions

When starting the signaling process, an **offer** is created by the user initiating the call. This offer includes a session description, in SDP format, and needs to be delivered to the receiving user, which we'll call the **callee**. The callee responds to the offer with an **answer** message, also containing an SDP description. Our signaling server will use WebSocket to transmit offer messages with the type `"video-offer"`, and answer messages with the type `"video-answer"`. These messages have the following fields:

`type`

The message type; either `"video-offer"` or `"video-answer"`.

`name`

The sender's username.

`target`

The username of the person to receive the description (if the caller is sending the message, this specifies the callee, and vice-versa).

`sdp`

The SDP (Session Description Protocol) string describing the local end of the connection from the perspective of the sender (or the remote end of the connection from the receiver's point of view).

At this point, the two participants know which codecs and video parameters are to be used for this call. They still don't know how to transmit the media data itself though. This is where Interactive Connectivity Establishment (ICE) (en-US) comes in.

### Exchanging ICE candidates

Two peers need to exchange ICE candidates to negotiate the actual connection between them. Every ICE candidate describes a method that the sending peer is able to use to communicate. Each peer sends candidates in the order they're discovered, and keeps sending candidates until it runs out of suggestions, even if media has already started streaming.

An `icecandidate` event is sent to the `RTCPeerConnection` to complete the process of adding a local description using `pc.setLocalDescription(offer)`.

Once the two peers agree upon a mutually-compatible candidate, that candidate's SDP is used by each peer to construct and open a connection, through which media then begins to flow. If they later agree on a better (usually higher-performance) candidate, the stream may change formats as needed.

Though not currently supported, a candidate received after media is already flowing could theoretically also be used to downgrade to a lower-bandwidth connection if needed.

Each ICE candidate is sent to the other peer by sending a JSON message of type `"new-ice-candidate"` over the signaling server to the remote peer. Each candidate message include these fields:

`type`

The message type: `"new-ice-candidate"`.

`target`

The username of the person with whom negotiation is underway; the server will direct the message to this user only.

`candidate`

The SDP candidate string, describing the proposed connection method. You typically don't need to look at the contents of this string. All your code needs to do is route it through to the remote peer using the signaling server.

Each ICE message suggests a communication protocol (TCP or UDP), IP address, port number, connection type (for example, whether the specified IP is the peer itself or a relay server), along with other information needed to link the two computers together. This includes NAT or other networking complexity.

**Примечание:** The important thing to note is this: the only thing your code is responsible for during ICE negotiation is accepting outgoing candidates from the ICE layer and sending them across the signaling connection to the other peer when your `onicecandidate` (en-US) handler is executed, and receiving ICE candidate messages from the signaling server (when the `"new-ice-candidate"` message is received) and delivering them to your ICE layer by calling `RTCPeerConnection.addIceCandidate()` (en-US). That's it.

The contents of the SDP are irrelevant to you in essentially all cases. Avoid the temptation to try to make it more complicated than that until you really know what you're doing. That way lies madness.

All your signaling server now needs to do is send the messages it's asked to. Your workflow may also demand login/authentication functionality, but such details will vary.

### Signaling transaction flow

The signaling process involves this exchange of messages between two peers using an intermediary, the signaling server. The exact process will vary, of course, but in general there are a few key points at which signaling messages get handled:

The signaling process involves this exchange of messages among a number of points:

* Each user's client running within a web browser
* Each user's web browser
* The signaling server
* The web server hosting the chat service

Imagine that Naomi and Priya are engaged in a discussion using the chat software, and Naomi decides to open a video call between the two. Here's the expected sequence of events:

![Diagram of the signaling process](/ru/docs/Web/API/WebRTC_API/Signaling_and_video_calling/webrtc_-_signaling_diagram.svg)

We'll see this detailed more over the course of this article.

### ICE candidate exchange process

When each peer's ICE layer begins to send candidates, it enters into an exchange among the various points in the chain that looks like this:

![Diagram of ICE candidate exchange process](/ru/docs/Web/API/WebRTC_API/Signaling_and_video_calling/webrtc_-_ice_candidate_exchange.svg)

Each side sends candidates to the other as it receives them from their local ICE layer; there is no taking turns or batching of candidates. As soon as the two peers agree upon one candidate that they can both use to exchange the media, media begins to flow. Each peer continues to send candidates until it runs out of options, even after the media has already begun to flow. This is done in hopes of identifying even better options than the one initially selected.

If conditions change—for example the network connection deteriorates—one or both peers might suggest switching to a lower-bandwidth media resolution, or to an alternative codec. This triggers a new exchange of candidates, after which a another media format and/or codec change may take place.

Optionally, see RFC 8445: Interactive Connectivity Establishment, section 2.3 ("Negotiating Candidate Pairs and Concluding ICE") if you want greater understanding of this process is completed inside the ICE layer. You should note that candidates are exchanged and media starts to flow as soon as the ICE layer is satisfied. This all taken care of behind the scenes. Our role is to simply send the candidates, back and forth, through the signaling server.

The client application
----------------------

The core to any signaling process is its message handling. It's not necessary to use WebSockets for signaling, but it is a common solution. You should, of course, select a mechanism for exchanging signaling information that is appropriate for your application.

Let's update the chat client to support video calling.

### Updating the HTML

The HTML for our client needs a location for video to be presented. This requires video elements, and a button to hang up the call:

```html
<div class="flexChild" id="camera-container">
  <div class="camera-box">
    <video id="received\_video" autoplay></video>
    <video id="local\_video" autoplay muted></video>
    <button id="hangup-button" onclick="hangUpCall();" disabled>Hang Up</button>
  </div>
</div>
```

The page structure defined here is using `<div>` elements, giving us full control over the page layout by enabling the use of CSS. We'll skip layout detail in this guide, but take a look at the CSS on Github to see how we handled it. Take note of the two `<video>` elements, one for your self-view, one for the connection, and the `<button>` element.

The `<video>` element with the `id` "`received_video`" will present video received from the connected user. We specify the `autoplay` attribute, ensuring once the video starts arriving, it immediately plays. This removes any need to explicitly handle playback in our code. The "`local_video`" `<video>` element presents a preview of the user's camera; specifiying the `muted` attribute, as we don't need to hear local audio in this preview panel.

Finally, the "`hangup-button`" `<button>`, to disconnect from a call, is defined and configured to start disabled (setting this as our default for when no call is connected) and apply the function `hangUpCall()` on click. This function's role is to close the call, and send a signalling server notification to the other peer, requesting it also close.

### The JavaScript code

We'll divide this code into functional areas to more easily describe how it works. The main body of this code is found in the `connect()` function: it opens up a `WebSocket` server on port 6503, and establishes a handler to receive messages in JSON object format. This code generally handles text chat messages as it did previously.

#### Sending messages to the signaling server

Throughout our code, we call `sendToServer()` in order to send messages to the signaling server. This function uses the WebSocket connection to do its work:

```js
function sendToServer(msg) {
  var msgJSON = JSON.stringify(msg);

  connection.send(msgJSON);
}
```

The message object passed into this function is converted into a JSON string by calling `JSON.stringify()`, then we call the WebSocket connection's `send()` (en-US) function to transmit the message to the server.

#### UI to start a call

The code which handles the `"userlist"` message calls `handleUserlistMsg()`. Here we set up the handler for each connected user in the user list displayed to the left of the chat panel. This function receives a message object whose `users` property is an array of strings specifying the user names of every connected user.

```js
function handleUserlistMsg(msg) {
  var i;
  var listElem = document.querySelector(".userlistbox");

  while (listElem.firstChild) {
    listElem.removeChild(listElem.firstChild);
  }

  msg.users.forEach(function (username) {
    var item = document.createElement("li");
    item.appendChild(document.createTextNode(username));
    item.addEventListener("click", invite, false);

    listElem.appendChild(item);
  });
}
```

After getting a reference to the `<ul>` which contains the list of user names into the variable `listElem`, we empty the list by removing each of its child elements.

**Примечание:** Obviously, it would be more efficient to update the list by adding and removing individual users instead of rebuilding the whole list every time it changes, but this is good enough for the purposes of this example.

Then we iterate over the array of user names using `forEach()`. For each name, we create a new `<li>` element, then create a new text node containing the user name using `createTextNode()`. That text node is added as a child of the `<li>` element. Next, we set a handler for the `click (en-US)` event on the list item, that clicking on a user name calls our `invite()` method, which we'll look at in the next section.

Finally, we append the new item to the `<ul>` that contains all of the user names.

#### Starting a call

When the user clicks on a username they want to call, the `invite()` function is invoked as the event handler for that `click (en-US)` event:

```js
var mediaConstraints = {
  audio: true, // We want an audio track
  video: true, // ...and we want a video track
};

function invite(evt) {
  if (myPeerConnection) {
    alert("You can't start a call because you already have one open!");
  } else {
    var clickedUsername = evt.target.textContent;

    if (clickedUsername === myUsername) {
      alert(
        "I'm afraid I can't let you talk to yourself. That would be weird.",
      );
      return;
    }

    targetUsername = clickedUsername;
    createPeerConnection();

    navigator.mediaDevices
      .getUserMedia(mediaConstraints)
      .then(function (localStream) {
        document.getElementById("local\_video").srcObject = localStream;
        localStream
          .getTracks()
          .forEach((track) => myPeerConnection.addTrack(track, localStream));
      })
      .catch(handleGetUserMediaError);
  }
}
```

This begins with a basic sanity check: is the user even connected? If there's no `RTCPeerConnection`, they obviously can't make a call. Then the name of the user that was clicked upon is obtained from the event target's `textContent` property, and we check to be sure that it's not the same user that's trying to start the call.

Then we copy the name of the user we're calling into the variable `targetUsername` and call `createPeerConnection()`, a function which will create and do basic configuration of the `RTCPeerConnection`.

Once the `RTCPeerConnection` has been created, we request access to the user's camera and microphone by calling `MediaDevices.getUserMedia()`, which is exposed to us through the `Navigator.mediaDevices.getUserMedia` (en-US) property. When this succeeds, fulfilling the returned promise, our `then` handler is executed. It receives, as input, a `MediaStream` object representing the stream with audio from the user's microphone and video from their webcam.

**Примечание:** We could restrict the set of permitted media inputs to a specific device or set of devices by calling `navigator.mediaDevices.enumerateDevices()` to get a list of devices, filtering the resulting list based on our desired criteria, then using the selected devices' `deviceId` (en-US) values in the `deviceId` field of the the `mediaConstraints` object passed into `getUserMedia()`. In practice, this is rarely if ever necessary, since most of that work is done for you by `getUserMedia()`.

We attach the incoming stream to the local preview `<video>` element by setting the element's `srcObject` (en-US) property. Since the element is configured to automatically play incoming video, the stream begins playing in our local preview box.

We then iterate over the tracks in the stream, calling `addTrack()` (en-US) to add each track to the `RTCPeerConnection`. Even though the connection is not fully established yet, it's important to begin sending media to it as soon as possible, because the media will help the ICE layer decide on the best connectivity approach to take, aiding in the negotiation process.

As soon as media is attached to the `RTCPeerConnection`, a `negotiationneeded` event is triggered at the connection, so that ICE negotiation can be started.

If an error occurs while trying to get the local media stream, our catch clause calls `handleGetUserMediaError()`, which displays an appropriate error to the user as required.

#### Handling getUserMedia() errors

If the promise returned by `getUserMedia()` concludes in a failure, our `handleGetUserMediaError()` function performs.

```js
function handleGetUserMediaError(e) {
  switch (e.name) {
    case "NotFoundError":
      alert(
        "Unable to open your call because no camera and/or microphone" +
          "were found.",
      );
      break;
    case "SecurityError":
    case "PermissionDeniedError":
      // Do nothing; this is the same as the user canceling the call.
      break;
    default:
      alert("Error opening your camera and/or microphone: " + e.message);
      break;
  }

  closeVideoCall();
}
```

An error message is displayed in all cases but one. In this example, we ignore `"SecurityError"` and `"PermissionDeniedError"` results, treating refusal to grant permission to use the media hardware the same as the user canceling the call.

Regardless of why an attempt to get the stream fails, we call our `closeVideoCall()` function to shut down the `RTCPeerConnection`, and release any resources already allocated by the process of attempting the call. This code is designed to safely handle partially-started calls.

#### Creating the peer connection

The `createPeerConnection()` function is used by both the caller and the callee to construct their `RTCPeerConnection` objects, their respective ends of the WebRTC connection. It's invoked by `invite()` when the caller tries to start a call, and by `handleVideoOfferMsg()` when the callee receives an offer message from the caller.

```js
function createPeerConnection() {
  myPeerConnection = new RTCPeerConnection({
    iceServers: [
      // Information about ICE servers - Use your own!
      {
        urls: "stun:stun.stunprotocol.org",
      },
    ],
  });

  myPeerConnection.onicecandidate = handleICECandidateEvent;
  myPeerConnection.ontrack = handleTrackEvent;
  myPeerConnection.onnegotiationneeded = handleNegotiationNeededEvent;
  myPeerConnection.onremovetrack = handleRemoveTrackEvent;
  myPeerConnection.oniceconnectionstatechange =
    handleICEConnectionStateChangeEvent;
  myPeerConnection.onicegatheringstatechange =
    handleICEGatheringStateChangeEvent;
  myPeerConnection.onsignalingstatechange = handleSignalingStateChangeEvent;
}
```

When using the `RTCPeerConnection()` constructor, we will specify an `RTCConfiguration` (en-US)-compliant object providing configuration parameters for the connection. We use only one of these in this example: `iceServers`. This is an array of objects describing STUN and/or TURN servers for the ICE (en-US) layer to use when attempting to establish a route between the caller and the callee. These servers are used to determine the best route and protocols to use when communicating between the peers, even if they're behind a firewall or using NAT (en-US).

**Примечание:** You should always use STUN/TURN servers which you own, or which you have specific authorization to use. This example is using a known public STUN server but abusing these is bad form.

Each object in `iceServers` contains at least a `urls` field providing URLs at which the specified server can be reached. It may also provide `username` and `credential` values to allow authentication to take place, if needed.

After creating the `RTCPeerConnection`, we set up handlers for the events that matter to us.

The first three of these event handlers are required; you have to handle them to do anything involving streamed media with WebRTC. The rest aren't strictly required but can be useful, and we'll explore them. There are a few other events available that we're not using in this example, as well. Here's a summary of each of the event handlers we will be implementing:

`RTCPeerConnection.onicecandidate` (en-US)

The local ICE layer calls your `icecandidate` event handler, when it needs you to transmit an ICE candidate to the other peer, through your signaling server. See Sending ICE candidates for more information and to see the code for this example.

`RTCPeerConnection.ontrack` (en-US)

This handler for the `track` event is called by the local WebRTC layer when a track is added to the connection. This lets you connect the incoming media to an element to display it, for example. See Receiving new streams for details.

`RTCPeerConnection.onnegotiationneeded` (en-US)

This function is called whenever the WebRTC infrastructure needs you to start the session negotiation process anew. Its job is to create and send an offer, to the callee, asking it to connect with us. See Starting negotiation to see how we handle this.

`RTCPeerConnection.onremovetrack`

This counterpart to `ontrack` is called to handle the `removetrack` event; it's sent to the `RTCPeerConnection` when the remote peer removes a track from the media being sent. See Handling the removal of tracks.

`RTCPeerConnection.oniceconnectionstatechange` (en-US)

The `iceconnectionstatechange` event is sent by the ICE layer to let you know about changes to the state of the ICE connection. This can help you know when the connection has failed, or been lost. We'll look at the code for this example in ICE connection state below.

`RTCPeerConnection.onicegatheringstatechange` (en-US)

The ICE layer sends you the `icegatheringstatechange` event, when the ICE agent's process of collecting candidates shifts, from one state to another (such as starting to gather candidates or completing negotiation). See ICE gathering state below.

`RTCPeerConnection.onsignalingstatechange` (en-US)

The WebRTC infrastructure sends you the `signalingstatechange` message when the state of the signaling process changes (or if the connection to the signaling server changes). See Signaling state to see our code.

#### Starting negotiation

Once the caller has created its `RTCPeerConnection`, created a media stream, and added its tracks to the connection as shown in Starting a call, the browser will deliver a `negotiationneeded` event to the `RTCPeerConnection` to indicate that it's ready to begin negotiation with the other peer. Here's our code for handling the `negotiationneeded` event:

```js
function handleNegotiationNeededEvent() {
  myPeerConnection
    .createOffer()
    .then(function (offer) {
      return myPeerConnection.setLocalDescription(offer);
    })
    .then(function () {
      sendToServer({
        name: myUsername,
        target: targetUsername,
        type: "video-offer",
        sdp: myPeerConnection.localDescription,
      });
    })
    .catch(reportError);
}
```

To start the negotiation process, we need to create and send an SDP offer to the peer we want to connect to. This offer includes a list of supported configurations for the connection, including information about the media stream we've added to the connection locally (that is, the video we want to send to the other end of the call), and any ICE candidates gathered by the ICE layer already. We create this offer by calling `myPeerConnection.createOffer()` (en-US).

When `createOffer()` succeeds (fulfilling the promise), we pass the created offer information into `myPeerConnection.setLocalDescription()` (en-US), which configures the connection and media configuration state for the caller's end of the connection.

**Примечание:** Technically speaking, the string returned by `createOffer()` is an RFC 3264 offer.

We know the description is valid, and has been set, when the promise returned by `setLocalDescription()` is fulfilled. This is when we send our offer to the other peer by creating a new `"video-offer"` message containing the local description (now the same as the offer), then sending it through our signaling server to the callee. The offer has the following members:

`type`

The message type: `"video-offer"`.

`name`

The caller's username.

`target`

The name of the user we wish to call.

`sdp`

The SDP string describing the offer.

If an error occurs, either in the initial `createOffer()` or in any of the fulfillment handlers that follow, an error is reported by invoking our `reportError()` function.

Once `setLocalDescription()`'s fulfillment handler has run, the ICE agent begins sending `icecandidate` events to the `RTCPeerConnection`, one for each potential configuration it discovers. Our handler for the `icecandidate` event is responsible for transmitting the candidates to the other peer.

#### Session negotiation

Now that we've started negotiation with the other peer and have transmitted an offer, let's look at what happens on the callee's side of the connection for a while. The callee receives the offer and calls `handleVideoOfferMsg()` function to process it. Let's see how the callee handles the `"video-offer"` message.

##### Handling the invitation

When the offer arrives, the callee's `handleVideoOfferMsg()` function is called with the `"video-offer"` message that was received. This function needs to do two things. First, it needs to create its own `RTCPeerConnection` and add the tracks containing the audio and video from its microphone and webcam to that. Second, it needs to process the received offer, constructing and sending its answer.

```js
function handleVideoOfferMsg(msg) {
  var localStream = null;

  targetUsername = msg.name;
  createPeerConnection();

  var desc = new RTCSessionDescription(msg.sdp);

  myPeerConnection
    .setRemoteDescription(desc)
    .then(function () {
      return navigator.mediaDevices.getUserMedia(mediaConstraints);
    })
    .then(function (stream) {
      localStream = stream;
      document.getElementById("local\_video").srcObject = localStream;

      localStream
        .getTracks()
        .forEach((track) => myPeerConnection.addTrack(track, localStream));
    })
    .then(function () {
      return myPeerConnection.createAnswer();
    })
    .then(function (answer) {
      return myPeerConnection.setLocalDescription(answer);
    })
    .then(function () {
      var msg = {
        name: myUsername,
        target: targetUsername,
        type: "video-answer",
        sdp: myPeerConnection.localDescription,
      };

      sendToServer(msg);
    })
    .catch(handleGetUserMediaError);
}
```

This code is very similar to what we did in the `invite()` function back in Starting a call. It starts by creating and configuring an `RTCPeerConnection` using our `createPeerConnection()` function. Then it takes the SDP offer from the received `"video-offer"` message and uses it to create a new `RTCSessionDescription` (en-US) object representing the caller's session description.

That session description is then passed into `myPeerConnection.setRemoteDescription()` (en-US). This establishes the received offer as the description of the remote (caller's) end of the connection. If this is successful, the promise fulfillment handler (in the `then()` clause) starts the process of getting access to the callee's camera and microphone using `getUserMedia()`, adding the tracks to the connection, and so forth, as we saw previously in `invite()`.

Once the answer has been created using `myPeerConnection.createAnswer()` (en-US), the description of the local end of the connection is set to the answer's SDP by calling `myPeerConnection.setLocalDescription()` (en-US), then the answer is transmitted through the signaling server to the caller to let them know what the answer is

Any errors are caught and passed to `handleGetUserMediaError()`, described in Handling getUserMedia() errors.

**Примечание:** As is the case with the caller, once the `setLocalDescription()` fulfillment handler has run, the browser begins firing `icecandidate` events that the callee must handle, one for each candidate that needs to be transmitted to the remote peer.

##### Sending ICE candidates

The ICE negotiation process involves each peer sending candidates to the other, repeatedly, until it runs out of potential ways it can support the `RTCPeerConnection`'s media transport needs. Since ICE doesn't know about your signaling server, your code handles transmission of each candidate in your handler for the `icecandidate` event.

Your `onicecandidate` (en-US) handler receives an event whose `candidate` property is the SDP describing the candidate (or is `null` to indicate that the ICE layer has run out of potential configurations to suggest). The contents of `candidate` are what you need to transmit using your signaling server. Here's our example's implementation:

```js
function handleICECandidateEvent(event) {
  if (event.candidate) {
    sendToServer({
      type: "new-ice-candidate",
      target: targetUsername,
      candidate: event.candidate,
    });
  }
}
```

This builds an object containing the candidate, then sends it to the other peer using the `sendToServer()` function previously described in Sending messages to the signaling server. The message's properties are:

`type`

The message type: `"new-ice-candidate"`.

`target`

The username the ICE candidate needs to be delivered to. This lets the signaling server route the message.

`candidate`

The SDP representing the candidate the ICE layer wants to transmit to the other peer.

The format of this message (as is the case with everything you do when handling signaling) is entirely up to you, depending on your needs; you can provide other information as required.

**Примечание:** It's important to keep in mind that the `icecandidate` event is **not** sent when ICE candidates arrive from the other end of the call. Instead, they're sent by your own end of the call so that you can take on the job of transmitting the data over whatever channel you choose. This can be confusing when you're new to WebRTC.

##### Receiving ICE candidates

The signaling server delivers each ICE candidate to the destination peer using whatever method it chooses; in our example this is as JSON objects, with a `type` property containing the string `"new-ice-candidate"`. Our `handleNewICECandidateMsg()` function is called by our main WebSocket incoming message code to handle these messages:

```js
function handleNewICECandidateMsg(msg) {
  var candidate = new RTCIceCandidate(msg.candidate);

  myPeerConnection.addIceCandidate(candidate).catch(reportError);
}
```

This function constructs an `RTCIceCandidate` (en-US) object by passing the received SDP into its constructor, then delivers the candidate to the ICE layer by passing it into `myPeerConnection.addIceCandidate()` (en-US). This hands the fresh ICE candidate to the local ICE layer, and finally, our role in the process of handling this candidate is complete.

Each peer sends to the other peer a candidate for each possible transport configuration that it believes might be viable for the media being exchanged. At some point, the two peers agree that a given candidate is a good choice and they open the connection and begin to share media. It's important to note, however, that ICE negotiation does *not* stop once media is flowing. Instead, candidates may still keep being exchanged after the conversation has begun, either while trying to find a better connection method, or simply because they were already in transport when the peers successfully established their connection.

In addition, if something happens to cause a change in the streaming scenario, negotiation will begin again, with the `negotiationneeded` event being sent to the `RTCPeerConnection`, and the entire process starts again as described before. This can happen in a variety of situations, including:

* Changes in the network status, such as a bandwidth change, transitioning from WiFi to cellular connectivity, or the like.
* Switching between the front and rear cameras on a phone.
* A change to the configuration of the stream, such as its resolution or frame rate.

##### Receiving new streams

When new tracks are added to the `RTCPeerConnection`— either by calling its `addTrack()` (en-US) method or because of renegotiation of the stream's format—a `track` event is set to the `RTCPeerConnection` for each track added to the connection. Making use of newly added media requires implementing a handler for the `track` event. A common need is to attach the incoming media to an appropriate HTML element. In our example, we add the track's stream to the `<video>` element that displays the incoming video:

```js
function handleTrackEvent(event) {
  document.getElementById("received\_video").srcObject = event.streams[0];
  document.getElementById("hangup-button").disabled = false;
}
```

The incoming stream is attached to the `"received_video"` `<video>` element, and the "Hang Up" `<button>` element is enabled so the user can hang up the call.

Once this code has completed, finally the video being sent by the other peer is displayed in the local browser window!

##### Handling the removal of tracks

Your code receives a `removetrack` event when the remote peer removes a track from the connection by calling `RTCPeerConnection.removeTrack()` (en-US). Our handler for `"removetrack"` is:

```js
function handleRemoveTrackEvent(event) {
  var stream = document.getElementById("received\_video").srcObject;
  var trackList = stream.getTracks();

  if (trackList.length == 0) {
    closeVideoCall();
  }
}
```

This code fetches the incoming video `MediaStream` from the `"received_video"` `<video>` element's `srcObject` attribute, then calls the stream's `getTracks()` (en-US) method to get an array of the stream's tracks.

If the array's length is zero, meaning there are no tracks left in the stream, we end the call by calling `closeVideoCall()`. This cleanly restores our app to a state in which it's ready to start or receive another call. See Ending the call to learn how `closeVideoCall()` works.

#### Ending the call

There are many reasons why calls may end. A call might have completed, with one or both sides having hung up. Perhaps a network failure has occurred, or one user might have quit their browser, or had a system crash. In any case, all good things must come to an end.

##### Hanging up

When the user clicks the "Hang Up" button to end the call, the `hangUpCall()` function is called:

```js
function hangUpCall() {
  closeVideoCall();
  sendToServer({
    name: myUsername,
    target: targetUsername,
    type: "hang-up",
  });
}
```

`hangUpCall()` executes `closeVideoCall()` to shut down and reset the connection and release resources. It then builds a `"hang-up"` message and sends it to the other end of the call to tell the other peer to neatly shut itself down.

##### Ending the call

The `closeVideoCall()` function, shown below, is responsible for stopping the streams, cleaning up, and disposing of the `RTCPeerConnection` object:

```js
function closeVideoCall() {
  var remoteVideo = document.getElementById("received\_video");
  var localVideo = document.getElementById("local\_video");

  if (myPeerConnection) {
    myPeerConnection.ontrack = null;
    myPeerConnection.onremovetrack = null;
    myPeerConnection.onremovestream = null;
    myPeerConnection.onicecandidate = null;
    myPeerConnection.oniceconnectionstatechange = null;
    myPeerConnection.onsignalingstatechange = null;
    myPeerConnection.onicegatheringstatechange = null;
    myPeerConnection.onnegotiationneeded = null;

    if (remoteVideo.srcObject) {
      remoteVideo.srcObject.getTracks().forEach((track) => track.stop());
    }

    if (localVideo.srcObject) {
      localVideo.srcObject.getTracks().forEach((track) => track.stop());
    }

    myPeerConnection.close();
    myPeerConnection = null;
  }

  remoteVideo.removeAttribute("src");
  remoteVideo.removeAttribute("srcObject");
  localVideo.removeAttribute("src");
  remoteVideo.removeAttribute("srcObject");

  document.getElementById("hangup-button").disabled = true;
  targetUsername = null;
}
```

After pulling references to the two `<video>` elements, we check if a WebRTC connection exists; if it does, we proceed to disconnect and close the call:

1. All of the event handlers are removed. This prevents stray event handlers from being triggered while the connection is in the process of closing, potentially causing errors.
2. For both remote and local video streams, we iterate over each track, calling the `MediaStreamTrack.stop()` (en-US) method to close each one.
3. Close the `RTCPeerConnection` by calling `myPeerConnection.close()` (en-US).
4. Set `myPeerConnection` to `null`, ensuring our code learns there's no ongoing call; this is useful when the user clicks a name in the user list.

Then for both the incoming and outgoing `<video>` elements, we remove their `src` and `srcObject` attributes using their `removeAttribute()` methods. This completes the disassociation of the streams from the video elements.

Finally, we set the `disabled` property to `true` on the "Hang Up" button, making it unclickable while there is no call underway; then we set `targetUsername` to `null` since we're no longer talking to anyone. This allows the user to call another user, or to receive an incoming call.

#### Dealing with state changes

There are a number of additional events you can set listeners for which notifying your code of a variety of state changes. We use three of them: `iceconnectionstatechange`, `icegatheringstatechange`, and `signalingstatechange`.

##### ICE connection state

`iceconnectionstatechange` events are sent to the `RTCPeerConnection` by the ICE layer when the connection state changes (such as when the call is terminated from the other end).

```js
function handleICEConnectionStateChangeEvent(event) {
  switch (myPeerConnection.iceConnectionState) {
    case "closed":
    case "failed":
    case "disconnected":
      closeVideoCall();
      break;
  }
}
```

Here, we apply our `closeVideoCall()` function when the ICE connection state changes to `"closed"`, `"failed"`, or `"disconnected"`. This handles shutting down our end of the connection so that we're ready start or accept a call once again.

##### ICE signaling state

Similarly, we watch for `signalingstatechange` events. If the signaling state changes to `closed`, we likewise close the call out.

```js
function handleSignalingStateChangeEvent(event) {
  switch (myPeerConnection.signalingState) {
    case "closed":
      closeVideoCall();
      break;
  }
}
```

**Примечание:** The `closed` signaling state has been deprecated in favor of the `closed` `iceConnectionState` (en-US). We are watching for it here to add a bit of backward compatibility.

##### ICE gathering state

`icegatheringstatechange` events are used to let you know when the ICE candidate gathering process state changes. Our example doesn't use this for anything, but it can be useful to watch these events for debugging purposes, as well as to detect when candidate collection has finished.

```js
function handleICEGatheringStateChangeEvent(event) {
  // Our sample just logs information to console here,
  // but you can do whatever you need.
}
```

Next steps
----------

You can now try out this example on Glitch to see it in action. Open the Web console on both devices and look at the logged output—although you don't see it in the code as shown above, the code on the server (and on GitHub) has a lot of console output so you can see the signaling and connection processes at work.

Another obvious improvement would be to add a "ringing" feature, so that instead of just asking the user for permission to use the camera and microphone, a "User X is calling. Would you like to answer?" prompt appears first.


Введение в протоколы WebRTC - Интерфейсы веб API

Введение в протоколы WebRTC
===========================

В этой статье представлены протоколы, поверх которых построен WebRTC API.

ICE
---

Interactive Connectivity Establishment (ICE) "Установка интерактивного подключения" представляет собой каркас, позволяющий вашему веб-браузеру соединяться с узлами. Есть много причин, почему прямое соединение от узла A к узлу B просто не будет работать. Оно должно обойти межсетевые экраны, которые будут препятствовать открытию соединений, дать вам уникальный адрес, если, как в большинстве ситуаций, ваше устройство не имеет публичного IP-адреса, и передавать данные через сервер, если ваш маршрутизатор не позволяет вам напрямую соединяться с узлами. ICE использует некоторые из следующих технических приёмов, описанных ниже, для достижения этой цели:

STUN
----

Session Traversal Utilities for **NAT** (STU**N**) (акроним в акрониме) это протокол для нахождения и определения вашего публичного адреса и любых ограничений в вашем маршрутизаторе, которые препятствуют прямому соединению с узлом.

Клиент отправит запрос к STUN серверу в интернете, который ответит публичным адресом клиента и, доступен ли, или нет, клиент за NAT маршрутизатором.

![An interaction between two users of a WebRTC application involving a STUN server.](/ru/docs/Web/API/WebRTC_API/Protocols/webrtc-stun.png)

NAT
---

Network Address Translation (NAT) используется для того, чтобы дать вашему устройству публичный IP-адрес. Маршрутизатор имеет публичный IP-адрес, а каждое устройство, подключённое к маршрутизатору имеет частный IP-адрес. Запросы будут транслированы от частного IP-адреса устройства к публичному IP-адресу маршрутизатора (с уникальным портом). Таким образом вам не нужен уникальный IP-адрес для каждого устройства, тем не менее, оно может быть обнаружено в интернете.

Некоторые маршрутизаторы имеют ограничения на то, кто может подключаться к устройствам в сети. Это может означать, что даже если мы имеем публичный IP-адрес, найденный STUN сервером, никто не может создать соединение. В этой ситуации нам нужно обратиться к TURN.

TURN
----

Некоторые маршрутизаторы, использующие NAT применяют ограничение, называемое "Симметричный NAT" (Symmetric NAT). Это означает, что маршрутизатор будет принимать соединения только от узлов, к которым вы ранее подключились.

Traversal Using Relays around NAT (TURN) предназначен для обхода ограничения "Симметричный NAT" путём открытия соединения с TURN сервером и ретрансляции всей информации через этот сервер. Вы создадите соединение с TURN сервером и сообщите всем узлам слать пакеты этому серверу, которые затем будут переправлены вам. Очевидно, что они приходят с некоторыми накладными расходами, поэтому это используется, только если нет других альтернатив.

![An interaction between two users of a WebRTC application involving STUN and TURN servers.](/ru/docs/Web/API/WebRTC_API/Protocols/webrtc-turn.png)

SDP
---

Session Description Protocol (SDP) - это стандарт для описания мультимедийного контента соединения, как например: разрешение, форматы, кодеки, шифрование и т.д. Так, чтобы оба узла могли понять друг друга, после того как данные начнут передаваться. Это, в сущности, метаданные, описывающие содержимое, а не медиа контент сам по себе.


Жизнь WebRTC-сессии - Интерфейсы веб API

Жизнь WebRTC-сессии
===================

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

Эта статья не вдаётся в детали фактически использованных API в установке и обработке WebRTC-соединения. Это просто обзор процесса в целом с некоторой информацией о том, для чего нужен каждый шаг. Смотрите статью Signaling and video calling, чтобы получить пример с пошаговым объяснением того, что делает код.

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

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

Установка соединения
--------------------

Интернет большой. Реально большой. Умные люди, несколько лет назад, заметив то, насколько он велик, каким большим он может стать и то как быстро растёт, а также ограничения 32-битной системы адресации протокола IP, и поняли, что нужно начать что-то делать, чтобы создать новую 64-битную систему адресации. Но в какой-то момент они так же пришли к выводу, что переход на новую систему займёт больше времени, чем продержатся 32-разрядные адреса. Затем другие умные люди придумали способ, позволяющий нескольким компьютерам использовать один и тот же 32-итный IP-адрес. Network Address Translation (NAT (en-US)) - это стандарт, который поддерживает разделение адреса путём маршрутизации входящих и исходящих пакетов данных в и из локальной сети (LAN), которые разделяют единственный WAN (глобальный) адрес.

Проблемой для пользователя является то, что каждый отдельный компьютер в сети Интернет не обязан иметь уникальный IP-адрес, и по сути, IP-адрес устройства может измениться не только тогда, когда оно перемещается из одной сети в другую, но и если их сетевой адрес был изменён NAT (en-US) и/или DHCP. Для разработчиков, пытающихся строить одноранговые сети, эта ситуация является хорошей головоломкой: без уникального идентификатора для каждого устройства, нет возможности моментально автоматически выяснить то, как подключиться к конкретному устройству в Интернет. Если вызнаете, с кем вы хотите поговорить, вам не обязательно знать, какой адрес у вашего собеседника.

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

Всё это входит в процесс сигнализации.

### Процесс Сигнализации

Сигнализация - это процесс передачи управляющей информации между двумя устройствами для определения протоколов связи, каналов, кодирования и формата медиа-данных, методов передачи данных, а также информации, необходимой для маршрутизации. Наиболее важная вещь, о которой нужно знать о процессе сигнализации для WebRTC - **этот процесс не определён в спецификации**.

Вы можете задаться вопросом, почему нечто основоположное для процесса установки WebRTC-соединения вынесено из спецификации? Ответ прост: потому как два устройства не могут контактировать друг с другом, и спецификация не может предусмотреть все возможные способы использования WebRTC, также это приобретает ещё больший смысл с точки зрения предоставления разработчику возможности выбора наиболее подходящей сетевой технологии и протоколов передачи сообщений.

Для обмена сигнальной информацией, вы можете выбрать отправку JSON-объектов через WebSocket-соединение, можете использовать протокол XMPP/SIP через соответствующий канал, так же можете использовать `XMLHttpRequest` через HTTPS с техникой пуллинга (HTTPS with polling), или же другие комбинации технологий, которые вам могут прийти в голову. Вы даже можете использовать электронную почту в качестве сигнального канала.

Стоит также отметить, что сигнальный канал может вообще находиться вне компьютерной сети. Один узел может выпустить объект данных, который затем может быть распечатан на принтере, физически перемещается (пешком или голубиной почтой) до другого устройства, данные вводятся в устройство, ответ устройства затем возвращается обратно, так же пешком, и так далее, пока WebRTC-соединение между узлами открыто. В этом случае, будет очень высокая латентность, но этот сценарий возможен.

#### Обмен информации во время процесса сигнализации

Существует три основных типа информации, которой нужно обмениваться во время процесса сигнализации:

* Управляющие сообщения, используемые для настройки, открытия и закрытия каналов коммуникации, а также для обработки ошибок
* Информация, необходимая для того, чтобы настроить соединение: информация об IP-адресе и порте необходима узлам, чтобы они могли разговаривать друг с другом.
* Необходимо согласовать медиа-потоки: какие могут использоваться между узлами кодеки и форматы медиа-данных? Все это необходимо согласовать до того, как будет установлена WebRTC-сессия.

Только после успешного завершения процесса сигнализации, может быть возможен процесс открытия WebRTC-соединения между узлами.

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

#### Процесс сигнализации

Существует последовательность действий, которую нужно выполнить, чтобы стало возможным начало WebRTC-сессии:

1. Каждый узел создаёт объект `RTCPeerConnection`, представляющий собой WebRTC-сессию и сохраняющийся до её завершения.
2. Каждый узел устанавливает обработчик события `icecandidate`,которая занимается отправкой этих кандидатов в другую сторону по каналу сигнализации.
3. Каждый узел устанавливает обработчик события `addstream`, которое срабатывает когда начинает приходить поток данных от удалённого узла. Этот обработчик должен подключить этот поток к потребителю, например к элементу `<video>`.
4. Вызывающий узел создаёт уникальный идентификатор, токен или нечто, что сможет идентифицировать вызов на сигнальном сервере, и обмениваться с принимающим узлом. Форма и содержимое идентификатора остаётся на усмотрение разработчика.
5. Каждый узел подключается к согласованному сигнальному серверу, такому например как известный обоим WebSocket-сервер, для обмена сообщениями.
6. Каждый узел сообщает сигнальному серверу, что хочет подключиться к одной и той же WebRTC-сессии (идентифицируемой токеном, определённым на шаге 4)
7. ***descriptions, candidates, etc. — more coming up***
Перезапуск сессии ICE агент
---------------------------

Иногда, во время срока службы WebRTC сессии, сетевые условия изменяются. Один из пользователей, возможно, перейдёт от сотовой сети к сети WiFi или сеть может стать перегруженной. Например: когда это произойдёт, ICE агент может перезапустить сессию. Это процесс, с помощью которого сетевое соединение перезапустится и восстановится, точно таким же образом выполняется начальная установка сессии, за одним исключением того пока не установится новая сессия. Тогда сессия сменяется и переходит к новому сетевому соединению, а старое соединение закрывается.

**Примечание:** Различные браузеры поддерживают перезапуск сессии при разных условиях. Не все браузеры будут выполнять перезапуск сессии из-за перегрузки сети, например:

Есть два уровня перезапуска сессии: полная перезагрузка сессии вызывает все мультимедийные потоки в сеансе и должны быть пересмотрены. Частичная перезагрузка сессии позволяет агенту сессии перезапустить конкретный медиапоток вместо того, чтобы перезапускать все медиаданные. Некоторые браузеры пока не поддерживают частичную перезагрузку сессии, однако. <<< Все зависит от вашего кодерства... >>>

Если вам необходимо изменить конфигурацию соединения каким-либо образом (например, изменение к другому набору связи), вы можете сделать это перед `RTCPeerConnection.setConfiguration()(перед назначением конфигурации)` с обновлённой `RTCConfiguration(конфигурацией)` перед повторным запуском движка.

Чтобы явно вызвать перезапуск сессии, нужно начать переговорный процесс с помощью вызова `RTCPeerConnection.createOffer(),` указав параметр iceRestart(перезапуск сессии) со значением истины(true). Затем обработать процесс соединения так, как вы это обычно делаете.

Transmission
------------

### getUserMedia

LocalMediaStream object

Reception
---------


Использование каналов данных в WebRTC - Интерфейсы веб API

Использование каналов данных в WebRTC
=====================================

Как только WebRTC соединение установлено, используя интерфейс `RTCPeerConnection`, приложение в состоянии отправлять и получать медиаданные между двумя узлами в соединении. Но от WebRTC можно получить больше. В этом руководстве мы изучим то, как добавить канал данных в соединение, который будет использован для безопасной передачи произвольных данных (данных любого типа, в любом формате).

**Примечание:** Поскольку все компоненты WebRTC требуют использования кодирования, любые данные, передаваемые через `RTCDataChannel` автоматически защищаются, используя Datagram Transport Layer Security (**DTLS**). Смотри Security ниже для подробной информации.

Создание канала данных
----------------------

Основной транспорт передачи данных, использующийся объектом типа `RTCDataChannel` (en-US) может быть создан двумя способами:

* Позволить WebRTC создать транспорт и сообщить об этом удалённому узлу (вызвав у него событие типа `datachannel` ). Это простой способ, и он подходит для многих случаев, но не достаточно гибок для широких нужд.
* Написать свои скрипты по согласованию транспорта данных, и сигнализированию другому узлу о необходимости присоединения к новому каналу данных.

Разберём оба случая, начиная с первого, как с наиболее распространённого.

### Автоматический режим согласования

Зачастую, разработчик может позволить объекту соединения обработать согласование `RTCDataChannel` (en-US) соединения за него. Для этого нужно вызвать метод `createDataChannel()` (en-US) без определения значения свойства `negotiated`, или определить свойство значением `false`. Это автоматически активирует `RTCPeerConnection` на обработку согласования соединения за разработчика, вызывая событие создание канала данных у удалённого узла, связывая два узла вместе по сети.

Вызов метода `createDataChannel()` немедленно возвращает объект типа `RTCDataChannel`. Подписываясь на событие `open` (en-US) , можно будет точно определить когда соединение успешно откроется.

```js
let dataChannel = pc.createDataChannel("MyApp Channel");

dataChannel.addEventListener("open", (event) => {
  beginTransmission(dataChannel);
});
```

### Ручной режим согласования

Для ручного согласования соединения, сначала необходимо создать новый объект типа `RTCDataChannel` (en-US), используя метод `createDataChannel()` (en-US) объекта `RTCPeerConnection`, определяя свойство `negotiated` в значение `true`. Это сигнализирует объекту соединения не пытаться согласовать соединение автоматически.

Затем нужно согласовать соединение, используя веб сервер или иные средства коммуникации. Этот процесс должен сигнализировать удалённому узлу, что нужно создать собственный объект типа `RTCDataChannel` со свойством `negotiated`, установленным в значение `true`, используя тот же идентификатор канала `id` (en-US). Это свяжет два объекта типа `RTCDataChannel` через объект типа `RTCPeerConnection`.

```js
let dataChannel = pc.createDataChannel("MyApp Channel", {
  negotiated: true,
});

dataChannel.addEventListener("open", (event) => {
  beginTransmission(dataChannel);
});

requestRemoteChannel(dataChannel.id);
```

В данном примере канал создаётся установкой значения свойства `negotiated` в `true`, затем вызывается функция `requestRemoteChannel()` , запуская согласование соединения для создания удалённого канала с тем же идентификатором как у локального канала. Таким образом создание каналов данных позволяет использовать различные свойства, создавая их декларативно, используя одно и тоже значение идентификатора канала `id`.

Буферизация
-----------

Каналы данных WebRTC поддерживают буферизацию исходящих данных. Это работает автоматически. Несмотря на то, что нет способа контролировать размер буфера, вы можете узнать, сколько данных в настоящее время буферизуется, и вы можете выбрать уведомление о событии, когда в буфере начинают заканчиваться данные в очереди. Это облегчает написание эффективных подпрограмм, которые гарантируют, что всегда есть данные, готовые к отправке, без чрезмерного использования памяти или полного переполнения канала.

Ограничения размеров сообщений
------------------------------

Для любых данных, передаваемых по сети, существуют ограничения по размеру. На фундаментальном уровне отдельные сетевые пакеты не могут быть больше определённого значения (точное число зависит от сети и используемого транспортного уровня). На уровне приложения, то есть в пределах user agent's реализация WebRTC, в которой работает ваш код, реализует функции поддержки сообщений, размер которых превышает максимальный размер пакета на транспортном уровне сети.

Это может усложнить ситуацию, поскольку вы не знаете, каковы ограничения по размеру для различных пользовательских агентов и как они реагируют на отправку или получение сообщения большего размера. Даже когда пользовательские агенты совместно используют одну и ту же базовую библиотеку для обработки данных протокола управления потоком (SCTP), могут существовать различия в зависимости от того, как используется библиотека. Например, и Firefox, и Google Chrome используют библиотеку `usrsctp` для реализации SCTP, но все ещё существуют ситуации, в которых передача данных по `RTCDataChannel` каналу может завершиться сбоем из-за различий в том, как они вызывают библиотеку и обрабатывают ошибки, которые она возвращает.

Когда два пользователя, использующие Firefox, обмениваются данными по каналу данных, ограничение размера сообщения намного больше, чем когда Firefox и Chrome обмениваются данными, потому что Firefox реализует устаревшую технику для отправки больших сообщений в нескольких сообщениях SCTP, чего нет в Chrome. Вместо этого Chrome увидит серию сообщений, которые он считает завершёнными, и доставит их получающему `RTCDataChannel` каналу в виде нескольких сообщений

Сообщения размером менее 16 КБ могут отправляться без проблем, поскольку все основные пользовательские агенты обрабатывают их одинаково.

### Проблемы с большими сообщениями

В настоящее время нецелесообразно использовать `RTCDataChannel` для сообщений размером более 64 КБ (16 КБ, если вы хотите поддерживать кросс-браузерный обмен данными). Проблема возникает из-за того факта, что SCTP - протокол, используемый для отправки и получения данных по `RTCDataChannel` - изначально был разработан для использования в качестве протокола сигнализации. Ожидалось, что сообщения будут относительно небольшими. Поддержка сообщений, превышающих размер сетевого уровня MTU, была добавлена в качестве запоздалой мысли, в случае, если сигнальные сообщения должны были быть больше, чем MTU. Эта функция требует, чтобы каждый фрагмент сообщения имел последовательные порядковые номера, поэтому они должны передаваться один за другим, без каких-либо других данных, чередующихся между ними.

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

Это станет проблемой, когда браузеры будут должным образом поддерживать текущий стандарт поддержки больших сообщений - флаг конца записи (EOR), который указывает, когда сообщение является последним в серии, которое следует рассматривать как одну полезную нагрузку. Это реализовано в Firefox 57, но ещё не реализовано в Chrome (см. Chromium Bug 7774). С поддержкой EOR полезная нагрузка `RTCDataChannel` может быть намного больше (официально до 256 КБ, но реализация Firefox ограничивает их колоссальным 1 ГБ). Даже при 256 кБ этого достаточно, чтобы вызвать заметные задержки при обработке срочного трафика.

Чтобы решить эту проблему, была разработана новая система планировщиков потоков (обычно называемая «спецификацией данных SCTP»), позволяющая чередовать сообщения, отправленные в разных потоках, включая потоки, используемые для реализации каналов данных WebRTC. Это предложение предложение все ещё находится в черновой форме IETF, но после его реализации оно позволит отправлять сообщения практически без ограничений по размеру, поскольку уровень SCTP автоматически чередует лежащие в основе под-сообщения, чтобы обеспечить возможность получения данных каждого канала.

Поддержка Firefox для ndata находится в процессе реализации. Команда Chrome отслеживает реализацию поддержки ndata в Chrome Bug 5696.

Большая часть информации в этом разделе частично основана на блоге Demystifyijng WebRTC's Data Channel Message Size Limitations, написанный Леннартом Гралем. Там он немного подробнее рассказывает, но поскольку браузеры были обновлены с тех пор, некоторые посты могут быть устаревшими. Кроме того, со временем поддержки будет становиться все больше, особенно после того, как EOR и поддержка ndata будут полностью интегрированы в основные браузеры.

Безопасность
------------

Все данные, переданные с помощью WebRTC, зашифрованы на основе Transport Layer Security (en-US) (TLS). Поскольку TLS используется для защиты каждого HTTPS-соединения, любые данные, которые вы отправляете по каналу данных, так же безопасны, как и любые другие данные, отправляемые или получаемые браузером пользователя.

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


WebRTC подключение - Интерфейсы веб API

WebRTC подключение
==================

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

**Примечание:** Эта страница требует серьёзной переделки для структурной целостности и полноты содержания. Много информации здесь - это хорошо, но организация являет собой путаницу, поскольку сейчас являет собой вид "местности разгрузки"(dumping ground).

Что такое Предложение/Ответ и Канал сигнализации?
-------------------------------------------------

К сожалению, WebRTC не может создавать соединения без какого-либо сервера посередине. Мы называем его "каналом сигнализации". Это любого рода канал связи для обмена информацией перед установкой соединения, будь то электронная почта, почтовая открытка или почтовый голубь... Зависит от вас.

Информация, которой мы должны обменяться - это "предложение" и "ответ", которые содержат SDP, упомянутую ниже.

Узел A, тот кто будет инициатором соединения, создаст "предложение". Затем отправит это "предложение" узлу B, используя выбранный "сигнальный канал". Узел B получит "предложение" от "сигнального канала" и создаст "ответ". Затем отправит его обратно узлу A посредством "сигнального канала".

### Описания сессии

Конфигурация конечной точки WebRTC-соединения называется **"описание сессии"(session description)**. Описание включает информацию о типе посылаемого медиа, его формате, используемом протоколе передачи, IP-адресе и порте конечной точки, и другую информацию, необходимую для описания конечной точки передачи медиа. Эта информация обменивается и хранится с помощью **"протокола описания сессии". Session Description Protocol**(SDP). Если вы хотите подробную информацию о формате данных SDP, вы можете найти её в RFC 2327.

Когда пользователь запускает WebRTC вызов другого пользователя, создаётся специальное описание, называемое **"предложение"(offer)**. Это описание включает всю информацию для соединения, о предлагаемой конфигурации вызывающего абонента. Получатель затем откликается **"ответом"(answer)**, являющимся описанием его конца соединения. Таким образом, оба устройства разделяют друг с другом информацию, необходимую для того, чтобы обмениваться медиа данными. Этот обмен обрабатывается с помощью "интерактивного создания подключения". Interactive Connectivity EstablishmentICE (en-US). ICE - протокол, который позволяет двум устройствам использовать посредника для обмена "предложениями"(offers) и "ответами"(answers), даже если эти два устройства разделены механизмом "преобразования сетевых адресов". (NAT (en-US)(Network Address Translation).

Каждый узел, тогда, держит два описания под рукой: **локальное описание (local description)**, описывающее себя и **удалённое описание(remote description)**, описывающее другой конец соединения.

Процесс "предложение/ответ"(offer/answer) выполняется как, когда соединение впервые устанавливается, так и в любой момент, когда формат соединения или другая конфигурация нуждается в изменении. Независимо от того, является ли это новым соединением, или реконфигурированием существующего, это основные шаги, которые должны произойти для обмена "предложением"(offer) и "ответом"(answer). Пропустим ICE-слой на данный момент:

1. Вызывающий вызывает `RTCPeerConnection.createOffer()` (en-US) для создания "предложения"(offer)
2. Вызывающий вызывает `RTCPeerConnection.setLocalDescription()` (en-US) для установки этого "предложения" как локального описания (то есть описания локального конца соединения).
3. Вызывающий использует сигнальный сервер для передачи "предложения" к требуемому получателю вызова.
4. Получатель получает "предложение" и вызывает `RTCPeerConnection.setRemoteDescription()` (en-US) для записи его, как удалённого описания(описания другого конца соединения).
5. Получатель делает всякую настройку, которую должен сделать для его конца соединения, включая добавления исходящих потоков для соединения.
6. Получатель затем создаёт "ответ"(answer) посредством вызова `RTCPeerConnection.createAnswer()` (en-US).
7. Получатель вызывает `RTCPeerConnection.setLocalDescription()` (en-US), чтобы установить "ответ"(answer) в качестве локального описания. Получатель теперь знает конфигурацию обоих концов соединения.
8. Получатель использует сигнальный сервер для отправки "ответа"(answer) вызывающему.
9. Вызывающий получает "ответ"(answer).
10. Вызывающий вызывает `RTCPeerConnection.setRemoteDescription()` (en-US) для установки "ответа"(answer) как удалённого описания для его конца соединения. Теперь известна конфигурация обоих узлов. Медиа начинает течь в соответствии с настройками.
### Рассматриваемые и текущие описания

Спускаясь на один шаг глубже в процесс, мы находим, что localDescription и remoteDescription, свойства, возвращаемые эти двумя описаниями, не так просты, как выглядят. Потому что во время повторных переговоров(перезаключения) (renegotiation), "предложение"(offer) может быть отклонено, поскольку оно предлагает несовместимый формат. Необходимо, чтобы каждая конечная точка имела возможность предложить новый формат, но не переключаться на него, пока он не принят другим узлом. По этой причине, WebRTC использует *"рассматриваемые"* и *"текущие"* "описания".

**"Текущее описание"(current description)** (которое возвращается свойствами `RTCPeerConnection.currentLocalDescription` и `RTCPeerConnection.currentRemoteDescription`) представляет собой описание, в данный момент, фактически используемое соединением. Это самое недавнее соединение, которое обе стороны полностью согласились использовать.

**"Рассматриваемое описание"(pending description)** (возвращаемое `RTCPeerConnection.pendingLocalDescription` (en-US) и `RTCPeerConnection.pendingRemoteDescription` (en-US)) указывает на то описание, которое в настоящий момент находится на рассмотрении после вызова setLocalDescription() или setRemoteDescription(), соответственно.

При чтении описания (возвращаемого `RTCPeerConnection.localDescription` (en-US) и `RTCPeerConnection.remoteDescription` (en-US)), возвращаемым значением является значение pendingLocalDescription/pendingRemoteDescription, если есть рассматриваемое описание (то есть, рассматриваемое описание не null). В противном случае, возвращается текущее описание (currentLocalDescription/currentRemoteDescription).

При изменении описания путём вызова setLocalDescription() или setRemoteDescription(), указанное описание устанавливается как "рассматриваемое описание"(pending description), и WebRTC-слой начинает оценивать, действительно ли это приемлемо. После того, как предложенное описание было согласовано, значение currentLocalDescription или currentRemoteDescription изменяется на "рассматриваемое описание"(pending description), и pending description устанавливается снова в null, указывая, что "отложенного описания"(pending description) не существует.

**Примечание:** pendingLocalDescription содержит не только "предложение" или "ответ" на стадии рассмотрения, но и каких-либо ICE-кандидатов, которые уже были собраны с тех пор, как "предложение" или "ответ" были созданы. Подобным образом, pendingRemoteDescription включает любых удалённых ICE-кандидатов, которые были предоставлены вызовами `RTCPeerConnection.addIceCandidate()` (en-US).

Смотрите отдельные статьи по этим свойствам и методам для большей конкретики.

Что такое ICE-кандидат?
-----------------------

В дополнение к обмену информацией о медиа(обсуждённой выше в offer/answer и SDP), узлы должны обменяться информацией о сетевом соединении. Об этом известно как о ICE-кандидате и деталях доступных методов, которыми узел может общаться (непосредственно или через TURN-сервер).

Весь обмен в сложной схеме
--------------------------

![A complete architectural diagram showing the whole WebRTC process.](/ru/docs/Web/API/WebRTC_API/Connectivity/webrtc-complete-diagram.png)